使用swagger生成介面文件
阿新 • • 發佈：2022-12-11
1、安裝
go get -u github.com/swaggo/swag/cmd/swag go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/files go get -u github.com/alecthomas/template
驗證安裝成功與否
$ swag -v swag version v1.8.8
2、寫註釋
註解說明
| 註解 | 描述 |
|---|---|
| @Summary | 摘要 |
| @Produce | API 可以產生的 MIME 型別的列表，MIME 型別你可以簡單的理解為響應型別，例如：json、xml、html 等等 |
| @Param | 引數格式，從左到右分別為：引數名、入參型別、資料型別、是否必填、註釋 |
| @Success | 響應成功，從左到右分別為：狀態碼、引數型別、資料型別、註釋 |
| @Failure | 響應失敗，從左到右分別為：狀態碼、引數型別、資料型別、註釋 |
| @Router | 路由，從左到右分別為：路由地址，HTTP 方法 |
例項：
// @title 部落格系統
// @version 1.0
// @description Go 語言程式設計之旅：一起用 Go 做專案
// @termsOfService https://github.com/go-programming-tour-book
func main() {
global.Logger.Infof("%s: go-programming-tour-book/%s", "eddycjy", "blog-service")
gin.SetMode(global.ServerSetting.RunMode)
router := routers.NewRouter()
s := &http.Server{
Addr: ":" + global.ServerSetting.HttpPort,
Handler: router,
ReadTimeout: global.ServerSetting.ReadTimeout,
WriteTimeout: global.ServerSetting.WriteTimeout,
MaxHeaderBytes: 1 << 20,
}
s.ListenAndServe()
}
// @Summary 獲取多個標籤
// @Produce json
// @Param name query string false "標籤名稱" maxlength(100)
// @Param state query int false "狀態" Enums(0, 1) default(1)
// @Param page query int false "頁碼"
// @Param page_size query int false "每頁數量"
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "請求錯誤"
// @Failure 500 {object} errcode.Error "內部錯誤"
// @Router /api/v1/tags [get]
func (t Tag) List(c *gin.Context) {}
// @Summary 新增標籤
// @Produce json
// @Param name body string true "標籤名稱" minlength(3) maxlength(100)
// @Param state body int false "狀態" Enums(0, 1) default(1)
// @Param created_by body string true "建立者" minlength(3) maxlength(100)
// @Success 200 {object} model.Tag "成功"
// @Failure 400 {object} errcode.Error "請求錯誤"
// @Failure 500 {object} errcode.Error "內部錯誤"
// @Router /api/v1/tags [post]
func (t Tag) Create(c *gin.Context) {}
// @Summary 更新標籤
// @Produce json
// @Param id path int true "標籤 ID"
// @Param name body string false "標籤名稱" minlength(3) maxlength(100)
// @Param state body int false "狀態" Enums(0, 1) default(1)
// @Param modified_by body string true "修改者" minlength(3) maxlength(100)
// @Success 200 {array} model.Tag "成功"
// @Failure 400 {object} errcode.Error "請求錯誤"
// @Failure 500 {object} errcode.Error "內部錯誤"
// @Router /api/v1/tags/{id} [put]
func (t Tag) Update(c *gin.Context) {}
// @Summary 刪除標籤
// @Produce json
// @Param id path int true "標籤 ID"
// @Success 200 {string} string "成功"
// @Failure 400 {object} errcode.Error "請求錯誤"
// @Failure 500 {object} errcode.Error "內部錯誤"
// @Router /api/v1/tags/{id} [delete]
func (t Tag) Delete(c *gin.Context) {}
3、生成
swag init
在執行命令完畢後，會發現在 docs 資料夾生成 docs.go、swagger.json、swagger.yaml 三個檔案。
4、路由
import (
...
_ "gin_blog/docs" //這裡引入自己的docs
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
func NewRouter() *gin.Engine {
r := gin.New()
r.Use(gin.Logger())
r.Use(gin.Recovery())
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
...
return r
}
5、訪問介面文件
在瀏覽器中訪問 Swagger 的地址 http://127.0.0.1:8000/swagger/index.html，就可以看到文件，其主要分為三個部分，分別是專案主體資訊、介面路由資訊、模型資訊，這三部分共同組成了我們主體內容。
參考：