由 Golang 程式碼產生 Restful API 文件，使用 Swagger 規範 (OpenAPI 2.0)

Swagger 是一套 RESTful API 描敘語法，近期發展改名成 OpenAPI 規範，其生態系統工具也發展相當強大，不僅能從 Swagger 轉換成可互動式的網頁說明文件，產生特定的程式語言的用戶端實作 (client implementation)，也可以產生伺服端樣板 (server template)。

在近期專案中需要開始撰寫 API 文件而發現了它，但我們已經在 Go 中實作完服務 API，因此找到 go-swagger 這套能分析 Go 程式碼以及註解，並產生對應 Swagger 2.0 的工具 (2017-7 已推出 Swagger 3.0)，之後再透過 swagger-codegen 產生文件以及所需的 client 實作。

工作流程圖

撰寫 go-swagger 註解

按照說明文件步驟添加註解，先在主文件 (package main) 開頭加入標誌：

//go:generate swagger generate spec

根據需求加入對應的標誌註解，從參考文件中的範例複製貼上，嘗試修改範例成需要的描述：

swagger:meta：描述 API meta data，版本、主機位置、認證方法以及聯絡資訊等等
swagger:route：描述 API 方法
swagger:params：描述一個或是多個 API 方法的輸入參數
swagger:response：描述 API 方法回應的資料結構
swagger:operation：描述 API 方法，相較於 swagger:route 能添加的參數比較多，但也較比較複雜，大量使用 YAML 來描述
更多請參考 goswagger 說明文件

在使用的過程中，還蠻常參考 Swagger specification，且大量使用 swagger:operation 來撰寫 API 描述，因為 swagger:route 有支援的參數還太少啊…例如已棄用的描述 deprecated，swagger:route 就沒有處理該參數。

執行 go-swagger 產生 Swagger 定義檔

取得 go-swagger binary，README 文件中有提到多種方式可下載，選擇使用 source code 來取得 go-swagger
```
go get -u github.com/go-swagger/go-swagger/cmd/swagger
```
在 go 專案目錄下，執行 go-swagger 工具分析程式碼：
```
swagger generate spec -o ./swagger.json
```
取得產生的 Swagger 定義檔 swagger.json
使用 Swagger 定義檔產生文件抑或是其他語言的程式碼實作

使用 swagger-codegen 產生說明文件

主要我們提供 API 說明文件給合作單位使用，因此使用 swagger-codegen 來產生 HTML 的說明文件。

先準備好 Java 環境，因為 swagger-codegen，採用 Java 開發
取得 binary，README 文件中有說明幾種取得方式，這邊選擇從 Maven.org 下載已編譯好的 swagger-codegen-cli.jar
執行指令產生輸入 Swagger 定義檔所對應的 API 說明文件 (output HTML)，更多關於指令請參考說明文件
```
java -jar ./swagger-codegen-cli.jar generate -i ./swagger.json -o ./docs/ -l html2
```

順帶一提的是，也可以使用網站版本的 codegen 服務來產生說明文件，例如 https://generator.swagger.io/?url=https://example.com/swagger.json，便會自動讀取指定 url 的定義檔，分析後產生說明文件，且該文件還能夠即時互動，可以直接在網頁上測試自家的 API 呢 (前提是 API server 要先處理好 CORS)。