Laravel 8 开发中使用 swagger-php 3 生成文档
最近在新项目开发的过程中我发现 swagger-php
升级了版本,而且和以前的文档注释写法有了蛮多的差别。官方文档也写的不是很详细,在这里我将结合自己封装的案例将 Swagger-PHP v3.x
的一些用法分享给大家。
介绍
API 开发目录
- 文档生成后效果
安装
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
composer require laravel/sanctum
Swagger 可复用的公用参数
- 我会把文档的一些公共参数( 如
@OA\OpenApi
,@OA\OpenApi
,@OA\SecurityScheme
)写到ApiController
里面。代码如下
- 图片对应
Swagger 请求参数
POST 请求
在 swagger-php 3.*
以前我们如果 Post 请求参数很多,那么在控制器我们可能写很多的注释。导致代码特别冗余。 swagger-php 3.*
我是通过 表单验证 来解决这个问题的。同时代码也更清晰规范。
- 用户注册案列分享,代码如下
在上面代码中,我们看不到任何需要请求的参数,@OA\RequestBody
通过 ref
关联到 #/components/schemas/RegisterRequest
,而我们刚好有个表单请求类 RegisterRequest
。在 swagger-php 3.*
我们可以把文档 post 参数的注释放到表单请求类 RegisterRequest
。RegisterRequest
代码如下:
- 生成文档效果
GET 请求
我们以获取用户列表和获取用户详情,分别演示路由参数和请求参数注释如何编写。
- 路由参数案例(获取用户详情)
- 请求参数案例(获取用户列表)
Swagger 返回参数
在 Api 返回的时候,有可能是列表,有可能是对象。如果对象参数特别多,按以前我们可能在控制器写很多注释文档,导致代码很难看,我在项目开发中是将返回的注释写到 API 资源 来解决这个问题。
返回数组列表
UserResource 代码
效果
返回对象
从上面我们可以发现 UserResource
是可以复用的,当 @OA\JsonContent(ref="#/components/schemas/UserResource")
里面有 type = array
返回的就是列表,不然就是对象。
异常返回
- ApiNotFoundException 代码
总结
我是通过 API 资源 和 表单验证 去拆解注释,同时达到 API 开发目录的规范。在我项目实际开发中,自己也基于这套规范收益良多。
本作品采用《CC 协议》,转载必须注明作者和本文链接
推荐文章: