登录
原创

Swagger php注解常用语法梳理

发布于 2020-11-05 阅读 194
  • 后端
  • 代码规范
  • PHP
  • API
  • Laravel
原创

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

Swagger 优势

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

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

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

示例演示渲染如下:

image.png

评论区

miya0315
5粉丝

励志做一条安静的咸鱼,从此走上人生巅峰。

0

0

0