不分组接口
项目开发中接口众多,需要对相同业务类型进行分组显示,否则就是这样的:
如果有个几十个接口的话,页面可想而知
分组接口
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进行分组需要根据实际业务情况进行设计