swagger-php 3.0分目录扫描,Swagger-php接口分组显示

不分组接口

项目开发中接口众多，需要对相同业务类型进行分组显示，否则就是这样的：

如果有个几十个接口的话，页面可想而知

分组接口

swagger-php 提供了tag,上面的情况是没有弄清楚tag的作用，才导致接口零散无须

在添加接口注解的时候合理充分的使用tag可以是接口测试页面变得简洁有序更友好：

定义顶层Tag

可以在控制器的顶层定义一个父级tag，添加业务描述和接口简介

/**

* 处理登录相关的逻辑

*

* Class LoginController

* @package App\Http\Controllers\Api

* @OA\Tag(

* name="登录鉴权",

* description = "用户登录鉴权，安全秘钥获取、登录状态、登出"

* )

* @OA\Tag(

* name="分组1",

* description = "用户登录鉴权，安全秘钥获取、登录状态、登出"

* )

* @OA\Tag(

* name="分组2",

* description = "用户登录鉴权，安全秘钥获取、登录状态、登出"

* )

*/

接口tag

接口定义和注解的时候添加tag，下面定义了三个tag，每一个接口可以属于多个tag分组，这里为了演示将接口进行了分组：定义分组(登录鉴权，分组1，分组2)；未定义的分组(分组3)

/**

* @OA\Get(

* path="/api/pub/key",

* operationId="apiLoginKey",

* tags={"登录鉴权","分组1"},

* summary="秘钥获取",

* description="发送手机验证妈的时候对手机号进行加密，进行发送",

* @OA\Response(

* response=200,

* description="successful operation",

* @OA\JsonContent(ref="#/components/schemas/MsgExport")

* )

* )

*

*

* @OA\Get(

* path="/api/login/status",

* tags={"登录鉴权","分组1","分组3"},

* summary="登录状态",

* description="Returns project data",

* @OA\Response(

* response=200,

* description="successful operation",

* @OA\JsonContent(ref="#/components/schemas/MsgExport")

* )

* )

*

* @OA\Post(

* path="/api/login",

* tags={"登录鉴权","分组2","分组3"},

* summary="手机验证码登录",

* description="用户登录(手机号+验证码)",

* @OA\Parameter(ref="#/components/parameters/authToken"),

* @OA\RequestBody(

* @OA\MediaType(

* mediaType="application/x-www-form-urlencoded",

* @OA\Schema(ref="#/components/schemas/MobileLogin")

* )

* ),

* @OA\Response(

* response=200,

* description="successful operation",

* @OA\JsonContent(

* ref="#/components/schemas/MsgExport",

* example={"code":0,"reason":"接口响应消息","result":{"status":1},"params":{}},

* )

* ),

*

* )

*

* @OA\Get(

* path="/api/login/logout",

* tags={"登录鉴权","分组2"},

* summary="登出",

* description="用户登出",

* @OA\Response(

* response=200,

* description="successful operation",

* )

* )

*/

页面渲染结果如下：

定义的分组顶部显示，未定义的分组3，最后显示：

如何合理的规划和使用tag进行分组需要根据实际业务情况进行设计