Golang項目自動生成swagger格式接口文檔方法（二）

作者：路多辛 2023-03-08 08:48:50

開發(fā) 開發(fā)工具

Swag是一款可以將Go的注釋轉(zhuǎn)換為Swagger2.0格式文檔的工具，生成接口文檔用到的注釋需要按照swag要求的格式書寫。

展示接口文檔的幾種方式

之前的文章??《Golang項目自動生成swagger格式接口文檔方法（一）》??已經(jīng)介紹過Golang項目借助swaggo來自動生成接口文檔方法，生成接口文檔主的主要目的是用來做更好的展示使用，展示方法一般有三種：

啟動一個swagger服務來展示；
將生成的swagger文檔導入三方接口管理工具進行展示；
三方工具請求swagger服務，定期將文檔同步到自己系統(tǒng)里面展示。

gin框架集成swagger服務

可以看出如果是使用第二種展示方式的話，上篇介紹的內(nèi)容就夠了。如果要實現(xiàn)第一和第三種方式，項目就需要集成swagger服務了。本文就以gin框架為例，來說明一下項目如何集成swagger服務。

先按照上篇文章介紹的方法安裝swag工具。然后創(chuàng)建示例項目，假如項目名稱為go-project-name，創(chuàng)建main.go文件（先只定義包名即可），main.go內(nèi)容如下

package main

使用swag init生成docs文件夾，目錄結(jié)構(gòu)如下：

├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
│── go.mod
│── go.sum
└── main.go

修改main.go文件，寫入如下示例代碼（需要好好體會示例代碼）：

package main

import (
  "net/http"
  
   "github.com/gin-gonic/gin"
   docs "github.com/go-project-name/docs"
   swaggerfiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
)
// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
   g.JSON(http.StatusOK,"helloworld")
}

func main()  {
   r := gin.Default()
   docs.SwaggerInfo.BasePath = "/api/v1"
   v1 := r.Group("/api/v1")
   {
      eg := v1.Group("/example")
      {
         eg.GET("/helloworld",Helloworld)
      }
   }
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
   r.Run(":8080")
}

執(zhí)行swag init后運行代碼，訪問http://localhost:8080/swagger/index.html即可看到接口定義列表。主流的三方接口文檔管理系統(tǒng)都會實現(xiàn)從swagger服務自動同步的功能，即訪問swagger服務的doc.json文件，將內(nèi)容同步到自己系統(tǒng)里，即定期訪問http://localhost:8080/swagger/doc.json。

責任編輯：姜華來源：今日頭條

Swag 工具