alextech / expressive-route-openapi-doc
从expressive路由生成OpenAPI架构文档
Requires
- php: ^7.1
- ext-json: *
- doctrine/inflector: ^1.3
- psr/container: ^1.0
- zendframework/zend-expressive: ^3.2
Requires (Dev)
- ext-json: *
- phpunit/phpunit: ^7.5
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
服务的一个实例。添加 Application
或 RouteCollector
(如果你正在使用 路径分割管道 在多个配置中定义路由,并且调用 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
- 模式文件将被写入的目录路径