利用swagger打造高可用專案檔案——GO篇

阿新 • • 發佈：2019-12-31

你是否也被沒有檔案的專案折磨？你是否也因為專案需要寫檔案而頭疼？你是否也被年久失修的檔案坑害？少年，吃下我這發安利吧！通過部署 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!