利用swagger打造高可用项目文档——GO篇

时间 2019-11-06

标签利用 swagger 打造可用项目文档繁體版

原文原文链接

你是否也被没有文档的项目折磨？你是否也由于项目须要写文档而头疼？你是否也被年久失修的文档坑害？少年，吃下我这发安利吧！经过部署 Swagger，这些问题都将远离你，精美、易读、可测试、时效性高的文档，不想试试么？html

引言

swagger的基本概念和本人构建整个项目的基础思路，和以前的文章，利用swagger打造高可用项目文档——PHP篇中提到的一致，这里再也不作赘述，这里只描述部署与使用过程当中的不一样点。git

部署

go的基础环境安装，请参考官方文档，这里假定你已经有了一个能够稳定运行的go环境。github

首先安装基础组件chrome
```
go get -u github.com/go-swagger/go-swagger/cmd/swagger
复制代码
```
这里建议直接使用go get进行安装，不少使用brew安装的项目，会遇到GOROOT路径没法正确读取的问题，若是遇到相似问题能够参考下面的issue json

issueapi

接口中添加注释框架

注释语法能够参考官方文档使用规则post

这里提供一组简单的例子，笔者使用的是go+kit，未使用框架
  
  因为go kit提供了endpoint层，request和response由服务框架自动生成，能够方便的在上面添加注释
  
  // Package classification Example api.
  //
  // This is an example api
  //
  //      Host: 127.0.0.1
  //      Version: 1.0.0
  //
  // swagger:meta
  
  package endpoint
  
  // swagger:parameters GetExampleRequest
  type GetExampleRequest struct {
  // in: query
  Id    string `json:"id"`
  }
  
  // example api response
  // swagger:response GetExampleResponse
  type GetExampleResponse struct {
      // response body
      // in: body
      Body struct {
          // the code og response
          //
          // Required: true
          Code    int             `json:"code"`
          // the message of response
          //
          // Required: true
          Message string          `json:"message"`
          // response data
          Data    interface{}     `json:"data"`
      }
  }
  
  // swagger:route GET /example tag GetExampleRequest
  //
  // example route
  //
  // This is an example route
  //
  // Responses:
  // 200: GetExampleResponse
复制代码

复制该例子，即可以获得一个具备标准化注释的接口测试

获取标准 Swagger Jsonui

只须要在项目根目录中执行

swagger generate spec -o ./swagger.json
复制代码

该命令会从项目的main.go文件开始扫描，解析全部的swagger注释此时，便会在项目的根路径下生成一个swagger.json文件，以上面提供的注释为例，产生内容以下

{
      "swagger": "2.0",
      "info": {
          "description": "This is an example api",
          "title": "Example api.",
          "version": "1.0.0"
      },
      "host": "127.0.0.1",
      "paths": {
          "/example": {
              "get": {
                  "description": "This is an example route",
                  "tags": [
                      "tag"
                  ],
                  "summary": "example route",
                  "operationId": "GetExampleRequest",
                  "parameters": [
                      {
                          "type": "string",
                          "x-go-name": "Id",
                          "name": "id",
                          "in": "query"
                      }
                  ],
                  "responses": {
                      "200": {
                          "$ref": "#/responses/GetExampleResponse"
                      }
                  }
              }
          }
      },
      "responses": {
          "GetExampleResponse": {
              "description": "example api response",
              "schema": {
                  "type": "object",
                  "required": [
                      "code",
                      "message"
                  ],
                  "properties": {
                      "code": {
                          "description": "the code og response",
                          "type": "integer",
                          "format": "int64",
                          "x-go-name": "Code"
                      },
                      "data": {
                          "description": "response data",
                          "type": "object",
                          "x-go-name": "Data"
                      },
                      "message": {
                          "description": "the message of response",
                          "type": "string",
                          "x-go-name": "Message"
                      }
                  }
              }
          }
      }
  }
复制代码

至此，一个标准的 Swagger Json数据便诞生了。接下来的思路就很简单了，新写一个接口，将该json文件直接输出，而后利用前文利用swagger打造高可用项目文档——PHP篇中提到的chrome插件直接打开接口便可。

至此，一个快捷方便的go swagger文档便诞生了，具体使用的方式，就看你们的我的喜爱了。Hope you enjoy it!

可参考文档