OpenAPI: Swagger API Swaggo/swag

Kimi

2 min readAug 4, 2020

目的

解決開發 API 文件, 但又不想花時間同時開發跟維護文件. 加個欄位還要跑去改文件.

Swagger 可快速產生API文件. 且多個程式語言皆有支援

Swaggo/swag 是由Golang撰寫, 且支援
gin
echo
buffalo
net/http
flamingo
fiber

‌此範例使用 gin 來實作. 藉由註解, Swagger就能產文件.依據格式寫出來的註解可對應到文檔說明

安裝 package (gin, swagger)

gin

go get -u github.com/gin-gonic/gin

swagger

go get -u github.com/swaggo/swag/cmd/swag

Demo範例,資料夾結構

├── Readme.md
├── app
│   ├── controllers
│   │   └── api
│   │       ├── test
│   │       │   └── test.go
│   │       └── v1
│   │           └── account
│   │               └── account.go
│   ├── models
│   │   ├── account.go
│   │   └── error.go
│   └── services
│       └── httputil
│           └── error.go
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── main.go
├── routes
│   └── routes.go
└── tmp
└── runner-build

導入 swagger 文檔, package, 匯入路由

main.go

Debug Mode 才將 Swagger 路由導入

Swagger 註解

Swagger 是藉由註解內容來產生文件的, 在main.go上面是一般API訊息. 每個api func 上面註解用來顯示使用方法,需要哪些參數,回傳結果等等

‌一般API訊息

title         簡單API專案的標題或主要的業務功能
version         目前這專案API的版本
description 簡單描述
tersOfService 服務條款
tag.name 標籤名稱
tag.description 標籤描述
tag.docs.url 標籤的外部文檔URL
tag.docs.description 標籤的外部文檔說明
contact.name 作者名稱
contact.url 作者網址
contact.email 作者email
license.name 許可證名稱
license.url 許可證網址
host         服務名稱或者是ip
BasePath 基本URL路徑, (/api/v1)
schemes         提供的協定, (http, https)

使用＠開頭當變數後面的值需使用一個空白

main.go

/*
@title Swagger Example API With Gin
@version 1.0
@description This is a sample server celler server.
@termsOfService http://swagger.io/terms/
@contact.name API Support
@contact.url http://www.swagger.io/support
@contact.email support@swagger.io
@license.name Apache 2.0
@license.url http://www.apache.org/licenses/LICENSE-2.0.html
@host localhost:5566
@BasePath /api/v1
@query.collection.format multi
@x-extension-openapi {"example": "value on a json format"}
*/func main() {...}

API操作

description	操作行為的詳細說明
summary	描述該API
id	用於標示API的唯一字符,在所有API操作中必須唯一。
tags	歸屬同一類的API的tag, 以逗號分隔
accept	request的context-type
produce	response的context-type
param	參數按照: `參數名` `參數類型` `參數的資料類型` `是否必填` `註解`
header	response header: `return code` `參數類型` `資料類型` `註解`
router	path httpMethod

app/controllers/api/v1/account/account.go

// AddAccount godoc
// @Summary X01 Add an account
// @Description add by json account
// @Tags accounts, accounts2
// @Accept  json
// @Produce  json
// @Param account body models.AddAccount true "Add account"
// @Success 200 {object} models.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts [post]func AddAccount(c *gin.Context) {...}