大家好，我叫謝偉，是一名程序員。
今天的主題：Swagger API 文檔
首先問(wèn)個(gè)問(wèn)題， API 文檔重不重要？
重要，前后端的交互一般流程是這樣的，后端暴露出API后，交給前端，前端根據(jù)API的響應(yīng)，編寫前端頁(yè)面，一定程度上API 是前后端的交互橋梁。
所以， 我覺(jué)得 API 文檔很重要。
那么API 文檔主要要包含哪些內(nèi)容？
- 路由：包括路徑參數(shù)、請(qǐng)求參數(shù)、還是請(qǐng)求體參數(shù)
- 動(dòng)作：HTTP 請(qǐng)求動(dòng)作，GET、POST、DELETE、PUT
- 響應(yīng)：請(qǐng)求之后的返回值包含哪些信息，一般是JSON
之前我也寫過(guò)使用Beego 構(gòu)建API 文檔，現(xiàn)在發(fā)現(xiàn)Beego 體量太大了。稍有點(diǎn)需求就需要更改。
所以，我不太喜歡體量大的框架。
回顧下傳統(tǒng)的做法是編寫 swagger.yml 或者 swagger.json 文件。
beego API 自動(dòng)化文檔的做法是編寫注釋，注釋內(nèi)包含全局信息或者編寫應(yīng)用注釋
今天介紹的是 gin 框架 和 gin-swagger 自動(dòng)構(gòu)建 API 文檔。
手法和 beego 構(gòu)建自動(dòng)化API文檔一樣。編寫全局信息和編寫應(yīng)用注釋。
1. doc
2. 做法
- 要知道 swagger 注釋的語(yǔ)法
- 如何在 gin 內(nèi)怎么使用
注釋語(yǔ)法這個(gè)，全靠查文檔。對(duì)著文檔來(lái)。
當(dāng)然我覺(jué)得最好的方法是什么呢，是模仿，找一個(gè)別人已經(jīng)寫好的，修修改改，看看能不能編譯通過(guò)，編譯通過(guò)后是不是你預(yù)期的結(jié)果。不是的話，繼續(xù)修修改改，再編譯，再看是不是你希望的結(jié)果。如此反復(fù)。
效果圖：
第一步：編寫全局信息注釋，在主函數(shù)上編寫
格式：// @param info
// @title Swagger Example API12222
// @version 1.0
// @description This is a sample server Petstore 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 petstore.swagger.io
// @BasePath /v1
func main() {
r := gin.Default()
r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.GET("/hello/:name", Name)
r.Run()
}
r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
這個(gè)路由和響應(yīng)需要有，路由隨便的定義，但我覺(jué)得我這種方式一目了然，知道是文檔。
其他注釋對(duì)照著參考文檔即可。
第二步：編寫應(yīng)用注釋
即在響應(yīng)函數(shù)的上方編寫注釋
type Message struct {
MessageInfo string `json:"message"`
}
func (m *Message) Serializer()Message{
return Message{
MessageInfo: m.MessageInfo,
}
}
// Name will print hello name
// @Summary Print
// @Accept json
// @Tags Name
// @Security Bearer
// @Produce json
// @Param name path string true "name"
// @Resource Name
// @Router /hello/{name} [get]
// @Success 200 {object} main.Message
func Name(c *gin.Context){
name := c.Param("name")
if name==""{
return
}
var message Message
message = Message{
MessageInfo: fmt.Sprintf("hello %s" ,name),
}
c.JSON(http.StatusOK, message.Serializer())
}
這里最好把響應(yīng)體統(tǒng)一成結(jié)構(gòu)體的形式。即
type Message struct {
MessageInfo string `json:"message"`
}
func (m *Message) Serializer()Message{
return Message{
MessageInfo: m.MessageInfo,
}
}
第三步：目錄下 執(zhí)行命令
swag init
自動(dòng)生成 docs 文件夾，內(nèi)含 swagger.json 、swagger.json 、 docs.go
編譯不通過(guò)，查看報(bào)錯(cuò)信息，修改注釋。
第四步：導(dǎo)入生成的 docs 文件
import (
"github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
_ "./docs" // docs is generated by Swag CLI, you have to import it.
"github.com/gin-gonic/gin"
"net/http"
"fmt"
)
即這個(gè) ./docs
第五步：go run main.go
訪問(wèn)：http://127.0.0.1:8080/docs/index.html
即可查看 swagger 文檔。
全文完，謝謝，我是謝偉，再會(huì)。
