背景

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了,更会出现之前的同学没有把接口文档交接清楚就离职，留下一个繁重复杂的项目，重新啃起来异常艰难，不亚于自己从头写一遍。因此仅仅只通过强制来规范大家是不够的。我们研究了Swagger到Yapi的打通方法。

有了它之后，我们可以做到每次写完代码，只需要顺便修改注释，然后提交，Yapi上就能自动更改我们的接口文档。

一、Swagger简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格Web服务。你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

---

二、Swagger搭建

​ 以下步骤建立在已经有能够成功运行go的环境上。

​ 在go-swagger官方教程上能看到最全的教程，有能力的可以直接走官方教程。

上面的所有下载方式都可行，但是为了兼容我们的所有情况，所以选择这种，直接下载代码

把命令精简一下：其实就干了两件事，

1. clone go-swagger的代码；
2. 把swaager加进GOROOT。

mkdir DownLoad
cd DownLoad
git clone https://github.com/go-swagger/go-swagger
cd DownLoad/go-swagger-master/cmd/swagger/
go install .

验证一下是否成功：

[work@hangchuang /]$ swagger -h
Usage:
  swagger [OPTIONS] <command>

Swagger tries to support you as best as possible when building APIs.

It aims to represent the contract of your API with a language agnostic description of your application in json or yaml.


Application Options:
  -q, --quiet                  silence logs
      --log-output=LOG-FILE    redirect logs to file

Help Options:
  -h, --help                   Show this help message

Available commands:
  diff      diff swagger documents
  expand    expand $ref fields in a swagger spec
  flatten   flattens a swagger document
  generate  generate go code
  init      initialize a spec document
  mixin     merge swagger documents
  serve     serve spec and docs
  validate  validate the swagger document
  version   print the version

2.搭建

• 这一部分全部都是关于swagger的用法的，先来个最简单的,接口注释，把样例上面的注释放复制到接口上方
  
  

• 样例文档注释
  

• 运行swagger，生成接口文档

  • 命令：swagger generate spec -o ./swagger.json
    

• 启动swagger服务，进入接口文档页面

  • 命令：swagger serve --no-open swagger.json
    

---

三、Swagger规范

Swagger注释的规范以及用法如下

1.swagger:meta

简介：swagger:meta 是你的所有的API的概要，我们用它来形成我们的API文档的开头介绍。

// Go-Swagger API.(title)
//
// 这是我们的测试API (description)
//
// 	   Terms Of Service:
//     there are no TOS at this moment, use at your own risk we take no responsibility
//
//     Schemes: http, https
//     Host: localhost
//     BasePath: /go-swagger/test
//     Version: 0.0.1
//     License: MIT http://opensource.org/licenses/MIT
//     Contact: Zhubangzheng<zhubangzheng@baidu.com> zhubangzheng@baidu.com
//
//     Consumes:
//     - application/json
//     - application/xml
//
//     Produces:
//     - application/json
//     - application/xml
//
//     Security:
//     - api_key:
//
//     SecurityDefinitions:
//     api_key:
//          type: apiKey
//          name: KEY
//          in: header
//     oauth2:
//         type: oauth2
//         authorizationUrl: /oauth2/auth
//         tokenUrl: /oauth2/token
//         in: header
//         scopes:
//           bar: foo
//         flow: accessCode
//
//     Extensions:
//     x-meta-value: value
//     x-meta-array:
//       - value1
//       - value2
//     x-meta-array-obj:
//       - name: obj
//         value: field
//
// swagger:meta
package test

注意：注释的结尾 swagger:meta和package之间不能有空行，否则无法被swagger识别。
注解用法：

注解	简介	用法
TermsOfService	服务条款	允许使用 url 或*文本定义来描述 API 的服务条款（别名**“TOS”**）
Consumes	入参	API 接收的内容的默认参数类型值列表
Produces	反参	API 返回的内容的默认参数类型值列表
Schemes	方案	API 接受的默认方案列表（可能的值：http、https、ws、wss）https 是配置时首选的默认方案
Version	版本	API 的当前版本
Host	主机	API的host，可以分成线上和线下
Base path	默认路径	API 的默认基本路径
Contact	联系人	有关 API 的联系人姓名，例如。ZhuBangzhengzhubangzheng@baidu.com
License	证书	证书的名称后跟证书的 URL，例如。MIThttp://opensource.org/license/MIT
Security	安全	键字典：[]string{scopes}
SecurityDefinitions	安全定义	支持的授权类型列表 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityDefinitionsObject
Extensions	拓展	Swagger Schema 的扩展列表。字段名称必须以 x- 开头 例如 x-internal-id。该值可以是 null、原始值、数组或对象。

---

2.swagger:route

swagger:route 是最主要的一个注释参数，是你的单个API接口的详细信息。

​ 格式：swagger:route [method] [path pattern] [tag1 tag2 tag3] [operation id]

​ **[method]**和 **[path pattern]必选，后面的[tag]根据你自己决定，首先是你当前接口的tag，然后再考虑加上其他。最后的[operation id]**是你的方法的唯一标识，如果仅是作为一个接口文档可以不填，但是它在很多地方都被用作方法名。例如用于客户端生成的方法。

  // ServeAPI serves the API for this record store
func ServeAPI(host, basePath string, schemes []string) error {
  // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
	//
	// Swagger测试接口
	//
	// 用于Swagger测试
	//
	//     Consumes:
	//     - application/json
	//     - application/x-protobuf
	//
	//     Produces:
	//     - application/json
	//     - application/x-protobuf
	//
	//     Schemes: http, https, ws, wss
	//
	//     Deprecated: true
	//
	//     Security:
	//       api_key:
	//       oauth: read, write
	//
	//     Responses:
	//       default: genericError
	//       200: someResponse
	//       422: validationError
  	mountItem("GET", basePath+"/{id}/checkout", nil)
}

Response和后面定义的swagger:response对应

注解用法：

注解	简介	用法
Consumes	入参	API 接收的内容的默认参数类型值列表
Produces	反参	API 返回的内容的默认参数类型值列表
Schemes	方案	API 接受的默认方案列表（可能的值：http、https、ws、wss）https 是配置时首选的默认方案
Deprecated	废弃	如果此值为 true，则该接口标记为已弃用
Security	安全	键字典：[]string{scopes}
Responses	响应	状态代码字典到命名响应

---

3.swagger:parameters

swagger:parameters 是接口的参数注释

格式：swagger:parameters [operationid1 operationid2]，parameters 通过**[operation id]**和route绑定。

参数的玩法很多，但是基本都用不上详细可以在官方文档查看swagger:parameters

因为我们主要使用GET、POST，而官网只介绍了GET方法，内网外网对于swagger:parameters注解的POST的用法介绍甚少，因此在这里介绍GET和POST的主要玩法即可。

GET:

// swagger:parameters swagger_test_checkout 
type SwaggerTest struct {
  // SwaggerTest接口测试参数1 (description)
  // required: true(是否必须)
  // in: query(参数所在的位置)
    ID uinat64 `json:"id"`
}

重点：GET方法的 in 注释 可接 query、header、cookie、path ，不同情况自定。

以上就是我们声明一个GET的参数的必要注释，其他都是非必要，如下图，可以根据自己的具体情况添加。

POST:

// swagger:parameters swagger_test_checkout 
type SwaggerTest struct {
  // SwaggerTest接口测试参数1 (description)
  // required: true(是否必须)
  // in: formData(参数所在的位置)
    ID uinat64 `json:"id"`
}

POST方法，参数的位置不在body，换句话说不能 in:body，而是要使用 in:formData，这样的格式导入到yapi之后才会出现在body里，且在本地的swagger ui中也才会正确显示。还有一点需要注意就是建议把swagger:route处的Consumes设置成 multipart/form-data，即

  // ServeAPI serves the API for this record store
func ServeAPI(host, basePath string, schemes []string) error {
  // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
	//
	// Swagger测试接口
	//
	// 用于Swagger测试
	//
  //     Consumes:
  //     multipart/form-data
  //
  //     ......
  	mountItem("GET", basePath+"/{id}/checkout", nil)
}

---

4.swagger:response

简介：swagger:response 是接口的响应注释

格式：swagger:response [response name] ，response 通过**[response name]**和route处定义的response绑定。

响应注释和参数的用法基本一样swagger:response，这里不需要赘述，直接举例。

// A ValidationError is an error that is used when the required input fails validation.
// swagger:response validationError
type ValidationError struct {
    // The error message
    // in: body
    Body struct {
        // The validation message
        //
        // Required: true
        // Example: Expected type int
        Message string
        // An optional field name to which this validation applies
        FieldName string
    }
}

重点：以上的用法是response的基础用法，但是实际上并不符合很多公司内部的结构定义，所以下面会讲真正的灵活且实用的用法。

1. swagger:response 可以出现在任意结构体上。不需要专门找到我们的response层，或者甚至没有response层的，而是每一个接口都定义了一个专门的response，最后再统一用interface处理，从而导致我们在历史项目里加上swagger异常困难。

   例如：

   // SwaggerTestResponse
   // swagger:response test_res
   type SwaggerTestResponse struct {
       // The error message
       // in: body
       Body struct {
           // The validation message
           //
           // Required: true
           // Example: Expected type int
           Message string
           // An optional field name to which this validation applies
           FieldName string
       }
   }
   

   **注意：**必须严格按照格式，Response结构体下嵌套一个Body结构体，也就是说如果是我们的历史项目，就得在Response外再包一层。
   例如：这是一正在是用的项目的Response返回，我们在上方加上swagger:response，后面跟上它的唯一id，test，在接口的返回处使用。

   // Test
   // swagger:response old_api_resp
   type OldAPIRes struct {
      // Test
      // in: body
      ID uint64
      Name string
      Time string
   }
   

     // ServeAPI serves the API for this record store
   func ServeAPI(host, basePath string, schemes []string) error {
     // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
   	//
   	// Swagger测试接口
   	//
   	// 用于Swagger测试
   	//
   	//     Consumes:
   	//     - multipart/form-data
   	//     Schemes: http
   	//     Responses:
   	//       200: old_api_resp
     	mountItem("GET", basePath+"/{id}/checkout", nil)
   }
   

   然后我们生成swagger.json，发现所有参数都被定义在了header下，而这些返回参数实际上应该位于body中，否则就无法被swagger ui和yapi识别。
   

   换句话说 swagger的in:body只识别结构体内嵌套的结构体，为了迎合swagger的识别要求，我们对结构进行改造，换成下面这种写法，就可以被识别在body里了

   // Test
   // swagger:response old_api_resp
   type OldAPIRes struct {
      // Test
       // in: body
      Body struct {
     	 ID uint64
   	   Name string
    	   Time string
       }
   }
   

   上面这种写法其实很不方便，所有的接口的Response下都要多加一层Body，这是不合理的，Swagger只是注释，不应该侵入代码，除非原有的结构就是如此，否则不推荐上面的格式。

2. **进阶版swagger:model：**解决了上面的痛点，真正做到了灵活好用。

   swagger:model其实也是一个swagger规范，用法非常灵活，详细的用法会在后面介绍，这里就提出用model解决response的方法。

   Response的注释修改

   // Test
   // swagger:model old_api_resp
   type OldAPIRes struct {
      ID uint64
      Name string
      Time string
   }
   

   Route注释修改

     // ServeAPI serves the API for this record store
   func ServeAPI(host, basePath string, schemes []string) error {
     // swagger:route GET /{id}/checkout SwaggerTest swagger_test_checkout
   	//
   	// Swagger测试接口
   	//
   	// 用于Swagger测试
   	//
   	//     Consumes:
   	//     - multipart/form-data
     //     Produces:
   	//     - application/json
   	//     Schemes: http
   	//     Responses:
     //       200: body:old_api_resp
     	mountItem("GET", basePath+"/{id}/checkout", nil)
   }
   

   命令修改，-m是扫描model

   swagger generate spec -m -o ./swagger.json 
   

   重新生成，然后搞定。

四、Swagger—Yapi

​ Yapi

​ 一个高效、易用、功能强大的API管理平台。

​ 为什么要打通Swagger到Yapi呢？理由很简单。Swagger的SwaggerUI远没有Yapi功能全面，而Yapi能支持导入Swagger.json格式的接口文档，Swagger的便利性和Yapi的全面性，我们把二者结合，从而实现更优的结果。

1.Nginx搭建

​ 经过上面的步骤我们应该已经在本地生成了我们接口的Swagger.json，而Yapi已经支持了手动导入和自动导入两种方式。

​ 手动导入：

自动导入：

我们需要的是什么？我们需要的是每次Swagger更新之后，Yapi都会自动更新我们的接口，那么我们自然需要使用Yapi的自动导入，因此我们只需要在自己的机器上搭建一个Nginx来做静态文件代理，就能实现。

下载并安装nginx

sudo yum install nginx -y

安装完成后查看

rpm -qa | grep nginx 

启动nginx

sudo systemctl start nginx

或是

sudo service nginx start

查看nginx状态

sudo systemctl status nginx

或是

sudo service nginx status

2.代理文件

进入nginx目录

cd /etc/nginx/

在conf.d目录下新增需要代理的端口

data映射的目录根据自己的实际情况，即swagger.json所在目录的位置而定

cd conf.d/
vim yapi.conf

server {
    listen       8888;
    server_name  localhost;

    location /data/ {
       alias '/home/work/Swagger/swagger-yapi/swagger-json/';
    }
}

重启nginx

sudo systemctl restart nginx

或

sudo service nginx restart

3.Yapi自动同步

ip对应你自己的机器ip

ip地址可以通过以下命令查看

hostname -i

如果被提示了

说明路径不对，可以把地址输入浏览器访问，自己调整到正确即可。

结语

​ Swagger还有很多的用法，光是通过swagger -h命令就能看到很多用法，而它的注释的用法也有很多，针对不同语言也有不同的写法。同理，Yapi作为一款功能强大的API管理平台也是一样的有很多的用法，比如在线mock接口等等。本文仅作为一个快速上手入门swagger到yapi的方法，通道搭建好之后，更多的用法就可以各位同学自己去挖掘。

作者：汽车研发部 朱邦政