go swagger生成介面檔案使用教學

2022-08-19 14:00:37

前言

這篇文章主要介紹了Go語言使用swagger生成介面檔案的方法，希望能夠對大家的學習或工作具有一定的幫助,需要的朋友可以參考下。

在前後端分離的專案開發過程中，如果後端同學能夠提供一份清晰明瞭的介面檔案，那麼就能極大地提高大家的溝通效率和開發效率。那如何維護介面檔案，歷來都是令人頭痛的，感覺很浪費精力，而且後續介面檔案的維護也十分耗費精力。在很多年以前，也流行用word等工具寫介面檔案，這裡面的問題很多，如格式不統一、後端人員消費精力大、檔案的時效性也無法保障。

針對這類問題，最好是有一種方案能夠既滿足我們輸出檔案的需要又能隨程式碼的變更自動更新，Swagger正是那種能幫我們解決介面檔案問題的工具。

Swagger介紹

Swagger是基於標準的 OpenAPI 規範進行設計的，本質是一種用於描述使用json表示的Restful Api的介面描述語言，只要照著這套規範去編寫你的註解或通過掃描程式碼去生成註解，就能生成統一標準的介面檔案和一系列 Swagger 工具。Swagger包括自動檔案，程式碼生成和測試用例生成。

1、安裝

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

在macOS中安裝 swag需要執行如下命令：

mv $GOPATH/bin/swag /usr/local/go/bin

2、檢測是否安裝成功

$ swag -v
swag version v1.8.4

3、安裝gin-swagger擴充套件

$ go get -u -v github.com/swaggo/gin-swagger
$ go get -u -v github.com/swaggo/files
$ go get -u -v github.com/alecthomas/template

使用

使用gin-swagger為你的程式碼自動生成介面檔案，一般需要下面三個步驟：

按照swagger要求給介面程式碼新增宣告式註釋。
使用swag工具掃描程式碼自動生成api介面檔案資料。
使用gin-swagger渲染線上介面檔案頁面。

1、新增註釋

go-swapper註解規範說明：

注：註解詳情可參見官網檔案Swagger Documentation

註解	描述
@Summary	摘要
@Produce	API 可以產生的 MIME 型別的列表，MIME 型別你可以簡單的理解為響應型別，例如：json、xml、html 等等
@Param	引數格式，從左到右分別為：引數名、入參型別、資料型別、是否必填、註釋
@Success	響應成功，從左到右分別為：狀態碼、引數型別、資料型別、註釋
@Failure	響應失敗，從左到右分別為：狀態碼、引數型別、資料型別、註釋
@Router	路由，從左到右分別為：路由地址，HTTP 方法

範例demo：

package main
import (
	"github.com/gin-gonic/gin"
	"github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "github/mwqnice/swag/docs" // 千萬不要忘了匯入把你上一步生成的docs
)
type Article struct{
	ID         uint32 `gorm:"primary_key" json:"id"`
	CreatedBy  string `json:"created_by"`
	ModifiedBy string `json:"modified_by"`
	CreatedOn  uint32 `json:"created_on"`
	ModifiedOn uint32 `json:"modified_on"`
	DeletedOn  uint32 `json:"deleted_on"`
	IsDel      uint8  `json:"is_del"`
	Title         string `json:"title"`
	Desc          string `json:"desc"`
	Content       string `json:"content"`
	CoverImageUrl string `json:"cover_image_url"`
	State         uint8  `json:"state"`
}
func NewArticle() Article {
	return Article{}
}
func main()  {
	r := gin.Default()
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.Run(":8088")
}
// @Summary 獲取單個文章
// @Produce json
// @Param id path int true "文章ID"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請求錯誤"
// @Failure 500 {object} string "內部錯誤"
// @Router /api/v1/articles/{id} [get]
func (a Article) Get(c *gin.Context) {
}
// @Summary 獲取多個文章
// @Produce json
// @Param name query string false "文章名稱"
// @Param tag_id query int false "標籤ID"
// @Param state query int false "狀態"
// @Param page query int false "頁碼"
// @Param page_size query int false "每頁數量"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請求錯誤"
// @Failure 500 {object} string "內部錯誤"
// @Router /api/v1/articles [get]
func (a Article) List(c *gin.Context) {
	return
}
// @Summary 建立文章
// @Produce json
// @Param tag_id body string true "標籤ID"
// @Param title body string true "文章標題"
// @Param desc body string false "文章簡述"
// @Param cover_image_url body string true "封面圖片地址"
// @Param content body string true "文章內容"
// @Param created_by body int true "建立者"
// @Param state body int false "狀態"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請求錯誤"
// @Failure 500 {object} string "內部錯誤"
// @Router /api/v1/articles [post]
func (a Article) Create(c *gin.Context) {
}
// @Summary 更新文章
// @Produce json
// @Param tag_id body string false "標籤ID"
// @Param title body string false "文章標題"
// @Param desc body string false "文章簡述"
// @Param cover_image_url body string false "封面圖片地址"
// @Param content body string false "文章內容"
// @Param modified_by body string true "修改者"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "請求錯誤"
// @Failure 500 {object} string "內部錯誤"
// @Router /api/v1/articles/{id} [put]
func (a Article) Update(c *gin.Context) {
	return
}
// @Summary 刪除文章
// @Produce  json
// @Param id path int true "文章ID"
// @Success 200 {string} string "成功"
// @Failure 400 {object} string "請求錯誤"
// @Failure 500 {object} string "內部錯誤"
// @Router /api/v1/articles/{id} [delete]
func (a Article) Delete(c *gin.Context) {
	return
}

2、生成介面檔案資料

格式化swag註解

$ swag fmt

在專案根目錄執行以下命令，使用swag工具生成介面檔案資料。

$ swag init

執行完上述命令後，如果你寫的註釋格式沒問題，此時你的專案根目錄下會多出一個docs資料夾。

./docs

├── docs.go

├── swagger.json

└── swagger.yaml

3、引入gin-swagger渲染檔案資料

然後在專案程式碼中註冊路由的地方按如下方式引入gin-swagger相關內容：

import (
	"github.com/gin-gonic/gin"
	"github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "github/mwqnice/swag/docs" // 千萬不要忘了匯入把你上一步生成的docs
)
//新增swagger存取路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

啟動專案，在瀏覽器中輸入地址：http://127.0.0.1:8088/swagger/index.html