go swagger 使用

奇蹟師發表於2021-12-13
GoSwagger

go swagger 自動生成文件

前言

  • 在寫完程式碼或者正在寫程式碼的時候，如果要與前端進行同步開發文件是必須的，但是如果在寫程式碼的時候發現介面要改，這個時候為了確保前端能夠理解又要修改開發文件，萬一忘記改了，可能無法面對前端的質問
  • 這個時候一個實時同步的開發文件就很重要了

學習使用

1.安裝

# 安裝 swag 如果不行直接上二進位制檔案 (國內的連線問題 -- 直接用二進位制檔案)
go get -u github.com/swaggo/swag/cmd/swag

## 安裝 gin-swagger 
go get github.com/swaggo/gin-swagger

## 安裝  swaggerFiles
go get github.com/swaggo/gin-swagger/swaggerFiles

2. 編寫註釋

1.編寫 main.go 中的註釋

// main.go 中新增註釋


// @title 標題
// @version 1.0 (版本)
// @description 宣告（可不寫）
// @termsOfService https://www.test.com

// @contact.name www.test.com
// @contact.url https://www.test.com
// @contact.email me@test.me

// @license.name Apache 2.0 (必填)
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:8080
// @BasePath
  • 注意
    @host 直接除錯 API地址
    @BasePath 基礎字首路徑

2.使用命令


     swag init
    # 或者
     swag init --parseDependency --parseInternal --parseDepth 1
  • 在 main.go中匯入 docs 資料夾
    import (
   _ "project_name/docs"
)

4.在需要編寫文件的 func 上編寫註釋

 type LoginReq{
     Code string `json:"code"` // 編碼
 }

 // @Summary 獲取 code
// @title 後臺介面
// @Tags 登入
// @Router /wxapp/login [post]
// @param param body LoginReq true "使用者請求引數"
// @Success 200 {object} JsonMsg
func Login(c *gin.Context) {
    // ...
}

5. 再次執行 swag init

3. 執行程式 go run main.go

go swagger 使用

yapi + swagger 文件管理

1.開啟 yapi 的一個專案至 資料管理

go swagger 使用

2.選擇 專案中 docs/swagger.json

go swagger 使用

3. 將 swagger.json 放入 yapi Swagger資料匯入則會自動匯入構建好的文件中

參考文件

結語

  • 感謝閱讀
本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章