swagger系列二：swagger 语法

在swagger-php的Example下有示例写法。拿过来分析记录。

swagger官方注解：https://bfanger.nl/swagger-explained/#schemaObject go

1. 文档标题部分

/**
 * @SWG\Swagger(
 *     schemes={"http"},
 *     host="api.com",
 *     basePath="/v1",
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="API接口文档",
 *         description="测试swagger文档项目",
 *         @SWG\Contact(
 *             name="wxp",
 *             email="[e-mail]"
 *         )
 *     ),
 *      @SWG\ExternalDocumentation(
 *         description="wxp",
 *         url="./"
 *     )
 * )
 */

效果图：

• schemes: 接口所支持的协议 (可以填多种协议)
• host：主机名或ip。
• basePath：提供API的基本路径，它是相对于host。必须以一个前导斜杠（/）开始. Base URL 是 host + basePath 拼接出来的。

• Info : 文档描述。

  • version ：版本号。
  • title :标题。
  • description : 描述信息。

• ExternalDocumentation":外部文档链接。

  • description:描述
  • url :跳转链接

• Contact ：联系开发者，发送邮件。

  • name : 开发者姓名
  • email :邮件地址。

2. tag标签部分，用于文档分类

/**
 * @SWG\Tag(
 *   name="pet",
 *   description="你的宠物信息",
 *   @SWG\ExternalDocumentation(
 *     description="查看更多",
 *     url=""
 *   )
 * )
 * @SWG\Tag(
 *   name="store",
 *   description="查看宠物店订单"
 * )
 * @SWG\Tag(
 *   name="user",
 *   description="用户操作记录",
 *   @SWG\ExternalDocumentation(
 *     description="关于宠物店",
 *     url="http://swagger.io"
 *   )
 * )
 */

• name : 名称(功能模块)
• description : 描述

3. 接口注释写法

    /**
     * @SWG\Get(
     *     path="/pet/{petId}",
     *     summary="通过ID查询宠物",
     *     description="返回宠物信息",
     *     operationId="getPetById",
     *     tags={"pet"},
     *     consumes={"application/json", "application/xml"},
     *     produces={"application/xml", "application/json"},
     *     @SWG\Parameter(
     *         description="ID of pet to return",
     *         in="path",
     *         name="petId",
     *         required=true,
     *         type="integer",
     *         format="int64"
     *     ),
     *     @SWG\Response(
     *         response=200,
     *         description="successful operation",
     *         @SWG\Schema(ref="#/definitions/Pet")
     *     ),
     *     @SWG\Response(
     *         response="400",
     *         description="Invalid ID supplied"
     *     ),
     *     @SWG\Response(
     *         response="404",
     *         description="Pet not found"
     *     ),
     *     security={
     *       {"api_key": {}}
     *     }
     * )
     */

• Get：请求的 HTTP 方法，支持GET/POST/PUT/DELETE 等 HTTP 标准请求方法
• path：请求的路径
• summary：接口简介，不能超过120个字符
• tags：接口标签，可以是多个
• description：接口描述，支持 Markdown 语法
• operationId：操作的 ID，全局唯一的接口标识
• consumes：接口接收的MIME类型，如 application/json
• produces：接口返回的MIME类型,如 application/json

• parameters：参数列表

  • description：参数描述
  • in：参数从何处来. 必填. 取值仅限: "query", "header", "path", "formData", "body"
  • name：参数名.
  • required：参数是否必须. 通过路径传参(in 取值 "path")时必须为 true.
  • type=参数类型. 取值仅限: "string", "number", "integer", "boolean", "array", "file"
  • format：参数格式，如"int64"

• response: 描叙了来自API操作的单个响应

  • response:返回码
  • description=描述
  • @SWGSchema(ref="#/definitions/Pet")： 引用definitions/Pet定义的对象

4. 定义对象

5.type 为array的写法

<?php
/**
 * @SWG\Schema(
 *     property="name",
 *     type="array",
 *     @SWG\Items(
 *          required={"username"}, 
 *          @SWG\Property(
 *              property="firstName",
 *              type="string",
 *              description="firstName"
 *          ),
 *          @SWG\Property(
 *              property="ID",
 *              type="integer",
 *              description="user_id"
 *          ),
 *          @SWG\Property(
 *              property="username",
 *              type="string",
 *              description="username"
 *          )
 *     )
 * )
 */