利用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!