Swagger php注解常用语法梳理

admin2024-07-01  10

Swagger php注解常用语法梳理

Swagger 优势

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

福利彩蛋:没有好玩的 API 接口?上百款免费接口等你来,免费 API,免费 API 大全

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

1、基础信息

字段名称类型描述
versionstring需要 Api版本信息。
titlestring需要 API的标题。
descriptionstring参数的简要说明。
termsOfServicestringAPI的服务条款。
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 联系信息

字段名称类型描述
urlstring联系人/组织的站点。
namestring联系人/组织的名称。
emailstring联系人/组织的邮箱。
 /**
 *@OA\Contact(
 *    url="http://www.example.com/support"
 *    email="miy@126.com",
 *    name="开发支持"
 * ),
 */

3、@OA\License 联系信息

字段名称类型描述
urlstring联系人/组织的站点。
namestring联系人/组织的名称。
emailstring联系人/组织的邮箱。
 /**
 * @OA\License(
 *      name="Apache 2.0",
 *      url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *)
 */

二、@OA\Server 服务器新

字段名称类型描述
urlstringApi服务器地址,。
descriptionstringApi服务器描述。
variablesstring联系人/组织的邮箱。
/**
 *  @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 参数描述

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

字段名称类型描述
namestring需要。参数的名称。参数名称区分大小写。
instring需要。参数的位置。可能的值是“query”,“header”,“path”,“formData”或“body”。
descriptionstring参数的简要说明。这可能包含使用的例子。
typestring参数的类型。取值权限:“string”,“number”,“integer”,“boolean”,“array”,“file”。
requiredboolean确定此参数是否是必需的。其默认值是false。
formatstring参数格式。
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 参数描述

字段名称类型描述
descriptionstring必填 响应的简短描述。。
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 鉴权

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

示例演示渲染如下:

Swagger php注解常用语法梳理,image.png,第1张

二、不分组接口

Swagger php注解常用语法梳理,image.png,第2张

三、分组接口

1.定义顶层Tag

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

2.接口tag


    /**    
     * @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",
     *       )
     * )
     */

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

Swagger php注解常用语法梳理,image.png,第3张

福利彩蛋:没有好玩的 API 接口?上百款免费接口等你来,免费 API,免费 API 大全

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明原文出处。如若内容造成侵权/违法违规/事实不符,请联系SD编程学习网:675289112@qq.com进行投诉反馈,一经查实,立即删除!