最近在新项目开发的过程中我发现 swagger-php 升级了版本，而且和以前的文档注释写法有了蛮多的差别。官方文档也写的不是很详细，在这里我将结合自己封装的案例将 Swagger-PHP v3.x 的一些用法分享给大家。

升级后的区别 Swagger-PHP v3.x Specification

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 协议》 ，转载必须注明作者和本文链接