通过 
搜索
搜索svensp / laravel-swagger
从 Laravel 路由定义和注解的 .yml 文件生成 openapi api-docs.json
0.4.0
2021-06-03 09:25 UTC
Requires
- php: >=7.4
- ext-json: *
- illuminate/console: ^7.0|^8.0
- illuminate/contracts: ^7.0|^8.0
- illuminate/http: ^7.0|^8.0
- illuminate/routing: ^7.0|^8.0
- illuminate/support: ^7.0|^8.0
- symfony/yaml: ^5.2
Requires (Dev)
- fakerphp/faker: ^1.9
- hamcrest/hamcrest-php: ^2.0
- mockery/mockery: ^1.4
- orchestra/testbench: ^6.11
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.5
README
此包旨在帮助您为基于 Laravel 的 API 生成 api-doc.yml 文件。
它不会为您生成整个 api-doc.yml，因此不充当 openapi 规范的完整抽象层。相反，将其视为 route:list，确保您的 open-api.yml 文件包含所有路由，并通知您在 open-api.yml 中存在但不在您的 Laravel 路由中的路由。
- 一个路由所在的控制器通过 @apidoc phpdoc 条目决定该路由出现在哪个 open-api.yml 中
- 多个控制器可以使用同一个 open-api.yml
安装
要安装此包，只需使用 composer 要求它
composer require svensp/laravel-swagger
使用
使用以下方式注释应出现在 open-api.yml 中的控制器
/**
* Class AuthController
* @apidoc path/to/your/open-api.yml
*/
class AuthController {
...
并使用以下方式创建它们
./artin open-api:generate
然而，建议发布配置文件并使用别名
./artisan vendor:publish --provider=LaravelSwagger\LaravelSwaggerProvider
默认设置将 @ 映射到 app_path()，我个人将名称 default 映射到 resource_path('/open-api.yml')
/**
* Class AuthController
* @apidoc @/resources/open-api.yml
* OR
* @apidoc default
*
*/
class AuthController {
...
标签
如果您为多个控制器使用相同的 open-api.yml，那么您可能希望为同一控制器的所有路由设置相同的标签。您可以使用 @apitags phpdoc 指令来自动完成此操作
/**
* Class AuthController
* @apidoc default
* @apitags auth
*
*/
class AuthController {
...
/**
* Class NewsController
* @apidoc default
* @apitags news
*
*/
class NewsController {
...
标签列表被解析为逗号分隔的列表。
路线图
- (可能) 添加由控制器函数使用的 FormRequests 中定义的参数
在 Laravel 之外使用
虽然我没有将包分成 Laravel 和 open-api 组件，但在 Laravel 之外使用它是可能的。只需实例化 LaravelSwagger\OpenApi\Updater，并将 DefinedRoute 数组传递给其 update 函数。从您选择的框架创建 DefinedRoutes 由您决定，以及传递
- 模板通常从配置中加载
- 别名通常从配置中加载
- 回调 - 在 Laravel 命令中设置，用于在找到没有 @apidoc 指令的控制器或 open-api.yml 中不再存在的路由时打印消息