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

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

引言

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

部署

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

首先安装基础组件
```
  go get -u github.com/go-swagger/go-swagger/cmd/swagger
```
这里建议直接使用go get进行安装，很多使用brew安装的项目，会遇到GOROOT路径无法正确读取的问题，如果遇到类似问题可以参考下面的issue
issue

接口中添加注释

  这里提供一组简单的例子，笔者使用的是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 Json

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

  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!

可参考文档