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="panxxxx@163.com"
* )
* ),
* @SWG\ExternalDocumentation(
* description="wxp",
* url="./"
* )
* )
*/


效果图：

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

• Info : 文档描述。

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

• ExternalDocumentation&＃8221;:外部文档链接。

  • 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：参数从何处来. 必填. 取值仅限: &＃8220;query&＃8221;, &＃8220;header&＃8221;, &＃8220;path&＃8221;, &＃8220;formData&＃8221;, &＃8220;body&＃8221;
  • name：参数名.
  • required：参数是否必须. 通过路径传参(in 取值 &＃8220;path&＃8221;)时必须为 true.
  • type=参数类型. 取值仅限: &＃8220;string&＃8221;, &＃8220;number&＃8221;, &＃8220;integer&＃8221;, &＃8220;boolean&＃8221;, &＃8220;array&＃8221;, &＃8220;file&＃8221;
  • format：参数格式，如&＃8221;int64&＃8243;

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

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

4. 定义对象

5.type 为array的写法

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