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

Posted 百度Geek说

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了接口文档自动更改?百度程序员开发效率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, --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

![图片](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 
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 说

百度官方技术公众号上线啦!

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

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

欢迎各位同学关注

以上是关于接口文档自动更改?百度程序员开发效率MAX的秘诀的主要内容,如果未能解决你的问题,请参考以下文章

pypi开源项目文档终极秘诀应对rst解析错误:The description failed to render in the default format of reStructuredText(代

pypi开源项目文档终极秘诀应对rst解析错误:The description failed to render in the default format of reStructuredText(代

如何优雅地进行接口管理?腾讯阿里大佬首次分享秘诀

php 代客站点使用代客定制驱动程序更改文档根目录

php 代客站点使用代客定制驱动程序更改文档根目录

直播报名中|云原生应用开发变革及效率提升秘诀