alextech/expressive-route-openapi-doc

此包最新版本(0.9.1)没有提供许可证信息。

从expressive路由生成OpenAPI架构文档

0.9.1 2019-01-04 00:05 UTC

This package is auto-updated.

Last update: 2024-09-09 13:48:18 UTC


README

从expressive路由生成OpenAPI文档骨架。

RouteOpenApiDoc 使用应用程序的路由配置来生成OpenAPI骨架。骨架包括用于编写路径及其参数描述的占位符,以及从路径段推断出的REST风格资源对应的模式引用。除了在如 swagger-ui 这样的查看器中显示外,这些模式还可以用于在中间件管道中验证 requestBody

其他API文档库侧重于解析注解。虽然docblock注解可能在MVC风格的框架中很有用,在这些框架中,路由表和控制器/操作位于不同的位置,使得没有额外的提示难以跟踪两者之间的连接,但对于中间件风格的框架,尤其是与 PSR-15 兼容的框架,路由和处理程序位于同一位置,使得为API文档生成器解析额外的docblocks变得多余。或者,他们尝试根据现有的API规范生成代码,这表现得过于CRUD,并且可能不与现有的代码库兼容。

用法

在你的路由配置函数中,获取 OpenApiWriter 服务的一个实例。添加 ApplicationRouteCollector(如果你正在使用 路径分割管道 在多个配置中定义路由,并且调用 writeSpec

use RouteApiDoc\RouterStrategy\RouterStrategyInterface;

return function (Application $app, MiddlewareFactory $factory, ContainerInterface $container) : void {
    // your API resources and handlers
    $app->get('/api/resources/:resource_id', []);
    $app->post('/api/resources', []);
    
    $apiWriter = $container->get(OpenApiWriter::class);
    $appWriter->addApplication($app);
    $apiWriter->writeSpec($app);
}

这将在下一个描述的输出目录中生成一个json文件 api_doc.json

如果你修改了生成的文件,因为你很可能只是修改了一个骨架,并且重新运行了生成器,更改将被合并。

默认情况下,每个猜测的资源将写入其自己的json模式文件。如果你希望所有模式都作为单一文档的一部分,请将 true 作为 writeSpec() 的参数传递。

由于文档生成是开发任务,并且会减慢请求,建议仅将上述行条件性地用于开发模式。

基本路径

如果你正在使用 $apiWriter->addRouteCollector()$apiWriter->addApplication() 添加多个路由容器,那么你很可能是使用 路径分割管道 技术来组织你的路由。在这种情况下,你需要让API生成器了解管道基本路径,因为Expressive没有将其暴露给路由收集。将其指定为 add 函数的第二个参数。基本路径也将成为从该路径开始的全部路由的标签。

配置

配置从应用程序配置的 openapi_writer 键读取。它期望有以下选项

[
    'router_strategy' => RouteApiDoc\RouterStrategy\ZendRouterStrategy::class
    'output_directory' => __DIR__ . '/spec'
]
  • router_strategy - 了解如何解释你选择的路由匹配库语法的策略的名称。(到目前为止仅支持Zend Router。FastRoute即将推出)
  • output_directory - 模式文件将被写入的目录路径