OpenAPITools 實踐

OpenAPITools 可以依據 REST API 描述檔案，自動生成服務端樁（Stub）代碼、用戶端 SDK 代碼，及文檔等。其是社群版的 Swagger ，差異可見：OpenAPI Generator vs Swagger Codegen。

本文将從零開始設計和編寫 API 檔案，并生成 Go Gin 服務端代碼，與 Python SDK 代碼。更多語言或架構，也是一樣操作的。

先熟悉下工具，直接用官方 Docker 鏡像生成 Petstore 樣例的 Go SDK 代碼：

生成代碼在目前目錄的 <code>./out/go</code> 。

打開 Swagger Editor <code>File &gt; Import URL</code> 檢視 <code>petstore.yaml</code> API：

檢視 <code>openapi-generator-cli</code> 用法:

打開 Swagger Editor 設計 API：

/albums

GET - Get all albums

POST - Create a new album

/albums/:id

GET - Get an album by its id

PUT - Update an album by its id

DELETE - Delete an album by its id

完整 API 描述檔案見 spec/api.yaml，主要包含三部分：

1 頭部： API 資訊

2 中間： <code>paths</code> 及其操作 (<code>get</code>, <code>post</code>, etc.)

3 底部： 可重用的 <code>components</code>，于文檔裡 <code>$ref</code> 引用

具體說明，請閱讀 OpenAPI Specification。

可以用線上服務快速生成代碼：

latest stable version: https://api.openapi-generator.tech

以下則是自己動手生成的過程。

生成 Go Gin 樁（Stub）代碼：

生成内容：

簡單實作 <code>GetAlbum</code> 接口，位于 <code>go/api_album.go</code>：

運作服務：

運作結果：

生成 Python SDK 代碼：

測試 SDK 使用，調用此前實作的 <code>GetAlbum</code> 接口：

實踐下來，感覺不錯。很多場合，生成 SDK 就夠用了。另外，生成自動化測試代碼，也值得一試。

GoCoding 個人實踐的經驗分享，可關注公衆号！