關於 web service, unity, blogger 等軟體工程筆記

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

Edit icon 沒有留言
Golang and Swagger

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 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)。

使用 Codegen 產生出的說明文件

使用 Codegen 產生出的說明文件

沒有留言: