mtrajano / laravel-swagger
自动为laravel项目生成swagger文档
Requires
Requires (Dev)
- php: >=7.0
- laravel/passport: ^8.0
- orchestra/testbench: ~4.0
- phpunit/phpunit: 8.3.*
Suggests
- ext-yaml: Required to use the YAML output option
This package is auto-updated.
Last update: 2024-09-11 01:22:21 UTC
README
请注意,此包已弃用,不再维护。目前,我将接受修复错误的pr,但将尽量避免向其添加任何大型功能。如果您有兴趣接管项目,请给我发邮件,我们可以协商。
Laravel Swagger会扫描您的laravel项目端点,并自动为您生成Swagger 2.0文档。
关于
Laravel Swagger基于Laravel的推荐实践工作。它将解析您的路由,并为每个路由生成一个路径对象。如果您在控制器操作中注入表单请求类作为请求验证,它也将为具有它们的每个请求生成参数。对于参数,它将考虑请求是GET/HEAD/DELETE还是POST/PUT/PATCH请求,并尽可能猜测应生成哪种参数对象类型。它还将生成包含在路由中的路径参数。最后,此包还将扫描您在操作方法中具有的任何文档,并将其作为摘要和描述添加到该路径中,同时添加任何适当的注释,如@deprecated。
需要注意的是,这个库倾向于显式。即使它们具有默认值,它也会选择包含键。例如,它选择说明一个路由具有弃用的值为false,而不是省略它。我认为这通过不省略重要信息使阅读文档更容易。用户可以选择在之后轻松地清理文件,如果他们选择省略默认值的话。
安装
可以通过在项目根目录中运行 composer require mtrajano/laravel-swagger
来轻松安装此包。
如果您正在运行Laravel < 5.5的版本,请确保将 Mtrajano\LaravelSwagger\SwaggerServiceProvider::class
添加到 config/app.php
文件中的 providers
数组中。
这将注册可用的artisan命令。
您还可以通过在项目根目录中运行 php artisan vendor:publish --provider "Mtrajano\LaravelSwagger\SwaggerServiceProvider"
来覆盖应用程序提供的默认配置,并更改在新建的 config/laravel-swagger.php
文件中创建的配置。
使用
生成swagger文档很容易,只需在项目根目录中运行 php artisan laravel-swagger:generate
即可。请注意,该命令将在控制台中打印输出。如果您想将文档保存到文件中,可以按照如下方式重定向输出:php artisan laravel-swagger:generate > swagger.json
如果您希望为您的部分路由生成文档,可以通过传递一个使用 --filter
的过滤器。例如:php artisan laravel-swagger:generate --filter="/api"
默认情况下,laravel-swagger以json格式打印文档。如果您想以yaml格式输出,可以使用 --format
标志来覆盖格式。如果您选择这样做,请确保已安装yaml扩展。
格式选项有
json
yaml
示例
假设您有一个路由 /api/users/{id}
,它映射到 UserController@show
您的示例控制器可能如下所示
/** * Return all the details of a user * * Returns the user's first name, last name and address * Please see the documentation [here](https://example.com/users) for more information * * @deprecated */ class UserController extends Controller { public function show(UserShowRequest $request, $id) { return User::find($id); } }
并且 FormRequest 类可能看起来像这样
class UserShowRequest extends FormRequest { public function rules() { return [ 'fields' => 'array' 'show_relationships' => 'boolean|required' ]; } }
运行 php artisan laravel-swagger:generate > swagger.json
将会生成以下文件
{ "swagger": "2.0", "info": { "title": "Laravel", "description": "Test", "version": "1.0.1" }, "host": "http:\/\/localhost", "basePath": "\/", "paths": { "\/api\/user\/{id}": { "get": { "summary": "Return all the details of a user", "description": "Returns the user's first name, last name and address Please see the documentation [here](https://example.com/users) for more information", "deprecated": true "responses": { "200": { "description": "OK" } }, "parameters": [ { "in": "path", "name": "id", "type": "integer", "required": true, "description": "" }, { "in": "query", "name": "fields", "type": "array", "required": false, "description": "" }, { "in": "query", "name": "show_relationships", "type": "boolean", "required": true, "description": "" } ] }, ... } } }