关于程序员:接口文档自动更改百度程序员开发效率MAX的秘诀

导读：置信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端常常埋怨后端给的接口文档与理论状况不统一。后端又感觉编写及保护接口文档会消耗不少精力，常常来不及更新。其实无论是前端调用后端，还是后端调用后端，都冀望有一个好的接口文档。然而随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了,更会呈现之前的同学没有把接口文档交接分明就到职，留下一个沉重简单的我的项目，从新啃起来异样艰巨，不亚于本人从头写一遍。因而仅仅只通过强制来标准大家是不够的。咱们钻研了Swagger到Yapi的买通办法。

有了它之后，咱们能够做到每次写完代码，只须要顺便批改正文，而后提交，Yapi上就能主动更改咱们的接口文档。

全文8310字，预计浏览工夫21分钟

一、Swagger简介

Swagger是一个标准和残缺的框架，用于生成、形容、调用和可视化RESTful格调Web服务。你只须要依照它的标准去定义接口及接口相干的信息。再通过Swagger衍生进去的一系列我的项目和工具，就能够做到生成各种格局的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

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

二、Swagger搭建

以下步骤建设在曾经有可能胜利运行go的环境上。在[go-swagger官网教程](https://goswagger.io/install.html)上能看到最全的教程，有能力的能够间接走官网教程。

1.装置

下面的所有下载方式都可行，然而为了兼容咱们的所有状况，所以抉择这种，间接下载代码。

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

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

mkdir DownLoadcd DownLoadgit clone https://github.com/go-swagger/go-swaggercd DownLoad/go-swagger-master/cmd/swagger/go install .

验证一下是否胜利：

[work@hangchuang /]$ swagger -hUsage:  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 fileHelp Options:  -h, --help                   Show this help messageAvailable 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

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3477fce1bfb34a6f87ca4545d97688be~tplv-k3u1fbpfcp-zoom-1.image)

三、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:metapackage test

留神：正文的结尾 swagger:meta和package之间不能有空行，否则无奈被swagger辨认。注解用法：

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 storefunc 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对应

注解用法：

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 storefunc 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 validationErrortype 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_restype 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_resptype OldAPIRes struct {// Test// in: body   ID uint64   Name string   Time string}

// ServeAPI serves the API for this record storefunc 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_resptype OldAPIRes struct {   // Test    // in: body   Body struct {       ID uint64       Name string        Time string    }}

1. 下面这种写法其实很不不便，所有的接口的Response下都要多加一层Body，这是不合理的，Swagger只是正文，不应该侵入代码，除非原有的构造就是如此，否则不举荐下面的格局。

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

   swagger:model其实也是一个swagger标准，用法非常灵活，具体的用法会在前面介绍，这里就提出用model解决response的办法。

   Response的正文批改

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

Route正文批改

  // ServeAPI serves the API for this record storefunc 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的办法，通道搭建好之后，更多的用法就能够各位同学本人去开掘。

举荐浏览：

｜百度搜寻中台海量数据管理的云原生和智能化实际

｜百度搜寻中“泥沙俱下”的加盟信息，如何靠AI 解决？

｜疾速剪辑-助力度咔智能剪辑提效实际

---------- END ----------

百度 Geek 说

百度官网技术公众号上线啦！

技术干货 · 行业资讯 · 线上沙龙 · 行业大会

招聘信息 · 内推信息 · 技术书籍 · 百度周边

欢送各位同学关注