五陵年少金市东，银鞍白马渡春风。这篇文章主要讲述接口文档自动更改？百度程序员开发效率MAX的秘诀相关的知识，希望能为你提供帮助。

文章图片


文章图片

一、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 -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, --quietsilence logs --log-output=LOG-FILEredirect logs to fileHelp Options: -h, --helpShow this help messageAvailable commands: diffdiff swagger documents expandexpand $ref fields in a swagger spec flattenflattens a swagger document generategenerate go code initinitialize a spec document mixinmerge swagger documents serveserve spec and docs validatevalidate the swagger document versionprint 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规范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	安全	键字典：[]stringscopes
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 [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对应
注解用法：

文章图片

3.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 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

1. 上面这种写法其实很不方便，所有的接口的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 listen8888; server_namelocalhost; location /data/ alias /home/work/Swagger/swagger-yapi/swagger-json/;

重启nginx

sudo systemctl restart nginx

或

sudo service nginx restart

3.Yapi自动同步
【接口文档自动更改（百度程序员开发效率MAX的秘诀）】ip对应你自己的机器ip
ip地址可以通过以下命令查看

hostname -i

文章图片

如果被提示了

文章图片

说明路径不对，可以把地址输入浏览器访问，自己调整到正确即可。
五、结语Swagger还有很多的用法，光是通过swagger -h命令就能看到很多用法，而它的注释的用法也有很多，针对不同语言也有不同的写法。同理，Yapi作为一款功能强大的API管理平台也是一样的有很多的用法，比如在线mock接口等等。本文仅作为一个快速上手入门swagger到yapi的方法，通道搭建好之后，更多的用法就可以各位同学自己去挖掘。
推荐阅读：
｜百度搜索中台海量数据管理的云原生和智能化实践
｜百度搜索中“鱼龙混杂”的加盟信息，如何靠AI 解决？
｜快速剪辑-助力度咔智能剪辑提效实践
---------- END ----------
百度 Geek 说
百度官方技术公众号上线啦！
技术干货 · 行业资讯 · 线上沙龙 · 行业大会
招聘信息 · 内推信息 · 技术书籍 · 百度周边
欢迎各位同学关注

推荐阅读

• 

  福建：五类困难群体可获医疗救助 最高补助90%
• 

  取保候审后判拘役还用坐牢么？
• 

  写出一个你喜欢的中国时尚品牌,为什么喜欢？
• 

  隔离霜用洗卸合一可以吗
• 

  如何预防记忆力减退
• 

  新车提车流程以及上牌是什么? 买新车提车到上牌流程
• 

  旅拍和摄影室拍摄你会选择哪个作为自己结婚的礼物？
• 

  恋活sunshine人物卡黑发单马尾偶像 黑发单马尾偶像怎么捏
• 

  40度冰箱故障维修指南：如何解决常见问题及保养技巧
• 

  蜂窝怎么吃可以治疗鼻炎 蜂窝怎么吃
• 

  干黄花菜怎么是苦的可以吃吗
• 

  前序遍历中序遍历后序遍历
• 

  收市评论|12月29日A股分析：创业板指跌1.4%，白酒板块大跌
• 

  米芾大师行书《参政帖》欣赏
• 

  小蜗牛注意力亲子教育.小贴士分享
• 

  微信勿扰模式
• 

  集美是什么梗
• 

  python去除数组中重复的元素，删除有序数组中的重复元素python
• 

  佳能入门单反相机推荐 佳能单反入门镜头推荐
• 

  登革热蚊子图片 如何消灭伊蚊，蟑螂怎么消灭

• 使用 Swoole 加速你的 CMS 系统
• 面试官说又逮到一个不会hashmap的#yyds干货盘点#
• java版gRPC实战之五（双向流）
• nginx+ipv6+https升级踩坑记
• Android 12 已来，你的 App 崩溃了吗（）
• #yyds干货盘点#mysql二进制安装
• Flutter 专题49 图解 Flutter 与 Android 原生交互 #yyds干货盘点#
• SHELL学习二（for语法）
• 一文汇总数据库基础知识点！（建议收藏）