Swagger php注解常用语法梳理

nbplus_007

于 2024-07-01 10:54:25 发布

阅读量1.6k

点赞数 56

分类专栏：经验分享文章标签： php android 开发语言 laravel 个人开发 swagger

本文链接：https://blog.csdn.net/nbplus_007/article/details/140094996

版权

经验分享专栏收录该内容

3 篇文章 0 订阅

订阅专栏

Swagger php注解常用语法梳理

快速编写你的 RESTFUL API 接口文档工具，通过注释定义接口和模型，可以和代码文件放置一起，也可以单独文件存放。

Swagger 优势

通过代码注解定义文档，更容易保持代码文档的一致性
模型复用，减少文档冗余，带来更可靠的文档
提供客户端访问接口，可以直接调试接口，不需要第三方工具进行调用测试接口
支持权限认证，等功能

下面详细介绍下Swagger的参数、对象和编写规范；一下是以Laravel 和Swagger为基础进行梳理分享，参考swagger官网文档进行整理，安装和简单使用 >>请这边走

福利彩蛋：没有好玩的 API 接口？上百款免费接口等你来，免费 API，免费 API 大全

一、 @OA\Info 声明一个API版本信息

Api版本信息、联系人/组织信息、许可信息

1、基础信息

参数

字段名称	类型	描述
version	string	需要 Api版本信息。
title	string	需要 API的标题。
description	string	参数的简要说明。
termsOfService	string	API的服务条款。
contact	联系对象	API的联系信息。
license	许可对象	API的许可证信息。

 /**
 * @OA\Info(
 *      version="1.0.0",
 *      title="服务端API",
 *      description="服务端API",
 *      termsOfService="http://example.com/terms/",
 *      @OA\Contact(
 *          url="http://www.example.com/support"
 *          email="miy@126.com",
 *          name="开发支持"
 *      ),
 *     @OA\License(
 *         name="Apache 2.0",
 *         url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *     )
 * )
 */

2、@OA\Contact 联系信息

API的公开联系信息：参数如下

字段名称	类型	描述
url	string	联系人/组织的站点。
name	string	联系人/组织的名称。
email	string	联系人/组织的邮箱。

 /**
 *@OA\Contact(
 *    url="http://www.example.com/support"
 *    email="miy@126.com",
 *    name="开发支持"
 * ),
 */

3、@OA\License 联系信息

API的公开许可信息：参数如下

字段名称	类型	描述
url	string	联系人/组织的站点。
name	string	联系人/组织的名称。
email	string	联系人/组织的邮箱。

 /**
 * @OA\License(
 *      name="Apache 2.0",
 *      url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *)
 */

二、@OA\Server 服务器新

API 服务器

字段名称	类型	描述
url	string	Api服务器地址，。
description	string	Api服务器描述。
variables	string	联系人/组织的邮箱。

/**
 *  @OA\Server(
 *      url=L5_SWAGGER_CONST_HOST,
 *      description="L5 Swagger OpenApi dynamic host server"
 *  )
 *
 *  @OA\Server(
*      url="https://projects.dev/api/v1",
 *      description="L5 Swagger OpenApi Server"
 * )
 */

三、@OA\Post、Get、Put、Delete 参数描述

字段名称	类型	描述
tags	boolean	接口名称。
path	string	需要。接口请求地址。
summary	string	接口简短描述，Ui界面在path后面展示，这个字段应该少于120个字符，对接友好
description	string	接口详情描述，接口展开描述接口功能或样例。
operationId	string	友好的操作描述名称，Id在api操作描述中名称唯一，工具库可以使用这个Id标识唯一的操作
security	安全对象	注明该请求使用哪些安全策略：值列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。该定义覆盖任何已声明的顶层security。要删除顶级安全声明，可以使用空数组。
parameters	参数对象	适用于此操作的参数列表。如果在路径项目中已经定义了一个参数，新的定义将覆盖它，但是不能删除它。该列表不得包含重复的参数。一个独特的参数是由一个名称和位置的组合来定义的。该列表可以使用引用对象链接到在Swagger对象参数中定义的参数(如果参数巨多可以使用ref引入params对象)。最多可以有一个“body”参数。
responses	响应对象	需要。执行此操作时返回的可能响应列表。
schemes	string	操作的传输协议。值必须是从列表：“http”，“https”，“ws”，“wss”。该值将覆盖Swagger对象schemes定义。
deprecated	boolean	声明此操作将被弃用。宣布的操作的使用应该被禁止。默认值是false。
produces	string	操作可以产生的类型列表。这将覆盖producesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述
consumes	string	该操作可以使用的类型列表。这将覆盖consumesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述。
externalDocs	外部文档对象	有关此操作的其他外部文档。

MIME类型必须类似如下（包含在 RFC 6838中)

    application/json
    application/xml
    application/x-www-form-urlencoded
    multipart/form-data
    text/plain; charset=utf-8
    text/html
    application/pdf
    image/png

示例

/**
 * 
 * @OA\Get(
 *      path="/users",
 *      operationId="getListOfUsers",
 *      tags={"Users"},
 *      description="Get list of users",
 *      security={{"Authorization-Bearer":{}}}, 
 *      @OA\Parameter(
 *         name="Authorization",
 *         in="header",
 *         required=true,
 *         description="Bearer {access-token}",
 *         @OA\Schema(
 *              type="bearerAuth"
 *         ) 
 *      ), 
 *      @OA\Response(
 *          response=200,
 *          description="Get list of users.",
 *          @OA\JsonContent(type="object",
 *              @OA\Property(property="message", type="string"),
 *              @OA\Property(property="data", type="array",
 *                  @OA\Items(type="object",
 *                      @OA\Property(property="id", type="integer"),
 *                      @OA\Property(property="name", type="string"),
 *                      @OA\Property(property="email", type="string"),
 *                  ),
 *              ),
 *          ),
 *       ),
 *       @OA\Response(response=401, description="Unauthorized"),
 *       @OA\Response(response=404, description="Not Found"),
 * )
 * 
 *
 */

1、@OA\Parameter 参数说明

字段名称	类型	描述
name	string	需要。参数的名称。参数名称区分大小写。
in	string	需要。参数的位置。可能的值是“query”，“header”，“path”，“formData”或“body”。
description	string	参数的简要说明。这可能包含使用的例子。
type	string	参数的类型。取值权限：“string”，“number”，“integer”，“boolean”，“array”，“file”。
required	boolean	确定此参数是否是必需的。其默认值是false。
format	string	参数格式。
default	*	默认值。

示例：

    /**
     *
     * @OA\Post(
     *      path="/api/login",
     *      tags={"手机验证码登录"},
     *      summary="手机验证码登录",
     *      description="用户登录（手机号+验证码）",
     *
     *      @OA\Parameter(ref="#/components/parameters/authToken"),//这里引入了authToken参数
     *      @OA\RequestBody( 
     *          @OA\MediaType(
     *              *mediaType="application/json",
     *              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":{}},
     *          )
     *       ),
     *
     * )
     *如果有多个参数的话且复用度较高，可以独立设置params，然后引用 
     * @OA\Parameter(
    *     in="header",
    *     name="authToken",
    *     description="测试HeaderToken",
    *     required=true,
    *     @OA\Schema(
    *          type="string"
    *     )
    * ),
     */

2、@OA\Response 参数描述

字段名称	类型	描述
description	string	必填响应的简短描述。。
schema	模式对象	响应结构的定义。它可以是一个基元，一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。
headers	标题对象	与响应一起发送的标题列表。
examples	示例对象	响应消息的一个例子。

示例：

    /*
     * @OA\Response(
     *          response=200,
     *          description="successful operation",
     *          @OA\JsonContent(ref="#/components/schemas/MsgExport")
     *       )
     */

3、@OA\Schema

/**
*定义可以复用的响应模板：
*
*  @OA\Schema(
*       schema="MsgExport",
*       required={"code","reason"},
*       @OA\Property(
*            property="code",
*            type="integer",
*            format="int32",
*            description="状态码"
*       ),
*       @OA\Property(
*            property="reason",
*            type="string",
*            description="提示消息"
*            ),
*       @OA\Property(
*            property="result",
*            type="array",
*            description="请求结果",
*            @OA\Items(
*                 @OA\Property(
*                      property="id",
*                      type="integer",
*                      description="ID"
*                  ),
*            )
*       ),
*       @OA\Property(
*            property="params",
*            type="array",
*            description="其他二外参数",
*       ),
* ),
*
*定义手机验证码登录属性模板：
*@OA\Schema(
*      description:"短信验证码登录属性",
*      schema="MobileLogin",
*      required={"mobile", "code","codeType"},
*      example={"mobile":"18913556768","code":"123123","codeType":1},
*      @OA\Property(
*          property="mobile",
*          type="string",
*          description="手机号"
*      ),
*      @OA\Property(
*          property="code",
*          type="string",
*          description="在验证码"
*      ),
*     @OA\Property(
*          property="codeType",
*          type="integer",
*          description="验证码类型",
*          default=1,
*      ),
* )
*/

4、@OA\SecurityScheme 鉴权

普通apiKey鉴权

/**
 * @OA\SecurityScheme(
 *     type="apiKey",
 *     description="全局添加API Token鉴权",
 *     name="authorization",
 *     in="header",
 *     securityScheme="Authorization-Bearer"
 * )
 *
 */

示例演示渲染如下：

二、不分组接口

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

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

三、分组接口

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

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

1.定义顶层Tag

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

/**
 * 处理登录相关的逻辑
 *
 * Class LoginController
 * @package App\Http\Controllers\Api
 * @OA\Tag(
 *     name="登录鉴权",
 *     description = "用户登录鉴权，安全秘钥获取、登录状态、登出"
 * )
 * @OA\Tag(
 *     name="分组1",
 *     description = "用户登录鉴权，安全秘钥获取、登录状态、登出"
 * )
 * @OA\Tag(
 *     name="分组2",
 *     description = "用户登录鉴权，安全秘钥获取、登录状态、登出"
 * )
 */

2.接口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进行分组需要根据实际业务情况进行设计

福利彩蛋：没有好玩的 API 接口？上百款免费接口等你来，免费 API，免费 API 大全

nbplus_007

关注

56
点赞
踩
19

收藏

觉得还不错? 一键收藏
0
评论
Swagger php注解常用语法梳理

快速编写你的 RESTFUL API 接口文档工具，通过注释定义接口和模型，可以和代码文件放置一起，也可以单独文件存放。Swagger 优势1. 通过代码注解定义文档，更容易保持代码文档的一致性2. 模型复用，减少文档冗余，带来更可靠的文档3. 提供客户端访问接口，可以直接调试接口，不需要第三方工具进行调用测试接口4. 支持权限认证，等功能
复制链接

扫一扫