相信很多程序猿和我一樣不喜歡寫API文檔。寫代碼多舒服，寫文檔不僅要花費(fèi)大量的時(shí)間，有時(shí)候還不能做到面面具全。但API文檔是必不可少的，相信其重要性就不用我說(shuō)了，一份含糊的文檔甚至能讓前后端人員打起來(lái)。 而今天這篇博客介紹的swaggo就是讓你只需要專注于代碼就可以生成完美API文檔的工具。廢話說(shuō)的有點(diǎn)多，我們直接看文章。

go語(yǔ)言中文文檔：www.topgoer.com

大概最后文檔效果是這樣的：

1.1.1. 關(guān)于Swaggo

或許你使用過(guò)Swagger, 而 swaggo就是代替了你手動(dòng)編寫yaml的部分。只要通過(guò)一個(gè)命令就可以將注釋轉(zhuǎn)換成文檔，這讓我們可以更加專注于代碼。

目前swaggo主要實(shí)現(xiàn)了swagger 2.0 的以下部分功能：

• 基本結(jié)構(gòu)(Basic Structure)
• API 地址與基本路徑(API Host and Base Path)
• 路徑與操作 (Paths and Operations)
• 參數(shù)描述(Describing Parameters)
• 請(qǐng)求參數(shù)描述(Describing Request Body)
• 返回描述(Describing Responses)
• MIME 類型(MIME Types)
• 認(rèn)證(Authentication)Basic AuthenticationAPI Keys
• 添加實(shí)例(Adding Examples)
• 文件上傳(File Upload)
• 枚舉(Enums)
• 按標(biāo)簽分組(Grouping Operations With Tags)
• 擴(kuò)展(Swagger Extensions)

下文內(nèi)容均以gin-swaggo為例 這里是demo地址

1.1.2. 使用

安裝swag cli 及下載相關(guān)包

要使用swaggo,首先需要安裝swag cli。

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

然后我們還需要兩個(gè)包。

# gin-swagger 中間件go get github.com/swaggo/gin-swagger# swagger 內(nèi)置文件go get github.com/swaggo/gin-swagger/swaggerFiles

在main.go內(nèi)添加注釋

package mainimport ( "net/http" "github.com/gin-gonic/gin" _ "github.com/student/0509/docs" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles")// @title Swagger Example API// @version 1.0// @description This is a sample server celler server.// @termsOfService https://www.topgoer.com// @contact.name www.topgoer.com// @contact.url https://www.topgoer.com// @contact.email me@razeen.me// @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host 127.0.0.1:8080// @BasePath /api/v1func main() { r := gin.Default() r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) v1 := r.Group("/api/v1") { v1.GET("/hello", HandleHello) // v1.POST("/login", HandleLogin) // v1Auth := r.Use(HandleAuth) // { // v1Auth.POST("/upload", HandleUpload) // v1Auth.GET("/list", HandleList) // } } r.Run(":8080")}

如上所示，我們需要導(dǎo)入

ginSwagger "github.com/swaggo/gin-swagger""github.com/swaggo/gin-swagger/swaggerFiles"

同時(shí)，添加注釋。其中：

• titile: 文檔標(biāo)題
• version: 版本
• description,termsOfService,contact ... 這些都是一些聲明，可不寫。
• license.name 額，這個(gè)是必須的。
• host,BasePath: 如果你想直接swagger調(diào)試API，這兩項(xiàng)需要填寫正確。前者為服務(wù)文檔的端口，ip。后者為基礎(chǔ)路徑，像我這里就是“/api/v1”。
• 在原文檔中還有securityDefinitions.basic,securityDefinitions.apikey等，這些都是用來(lái)做認(rèn)證的，我這里暫不展開(kāi)。

到這里，我們?cè)趍ian.go同目錄下執(zhí)行swag init就可以自動(dòng)生成文檔，如下：

E:goprojectsrcgithub.comopgoer>swag init2020/05/13 16:28:02 Generate swagger docs....2020/05/13 16:28:02 Generate general API Info, search dir:./2020/05/13 16:28:02 create docs.go at docs/docs.go2020/05/13 16:28:02 create swagger.json at docs/swagger.json2020/05/13 16:28:02 create swagger.yaml at docs/swagger.yaml

然后我們?cè)趍ain.go導(dǎo)入這個(gè)自動(dòng)生成的docs包，運(yùn)行：

package mainimport ( "github.com/gin-gonic/gin" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" _ "github.com/razeencheng/demo-go/swaggo-gin/docs")// @title Swagger Example API// @version 1.0// ...E:goprojectsrcgithub.comopgoer>go run main.go[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production. - using env: export GIN_MODE=release - using code: gin.SetMode(gin.ReleaseMode)[GIN-debug] GET /swagger/*any --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (3 handlers)[GIN-debug] GET /api/v1/hello --> main.HandleHello (3 handlers)[GIN-debug] Listening and serving HTTP on :8080

瀏覽器打開(kāi)http://127.0.0.1:8080/swagger/index.html, 我們可以看到如下文檔標(biāo)題已經(jīng)生成。

1.1.3. 在Handle函數(shù)上添加注釋

接下來(lái)，我們需要在每個(gè)路由處理函數(shù)上加上注釋，如：

package mainimport ( "net/http" "github.com/gin-gonic/gin" _ "github.com/student/0509/docs" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles")// @title Swagger Example API// @version 1.0// @description This is a sample server celler server.// @termsOfService https://www.topgoer.com// @contact.name www.topgoer.com// @contact.url https://www.topgoer.com// @contact.email me@razeen.me// @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host 127.0.0.1:8080// @BasePath /api/v1func main() { r := gin.Default() r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) v1 := r.Group("/api/v1") { v1.GET("/hello", HandleHello) // v1.POST("/login", HandleLogin) // v1Auth := r.Use(HandleAuth) // { // v1Auth.POST("/upload", HandleUpload) // v1Auth.GET("/list", HandleList) // } } r.Run(":8080")}// @Summary 測(cè)試SayHello// @Description 向你說(shuō)Hello// @Tags 測(cè)試// @Accept json// @Param who query string true "人名"// @Success 200 {string} string "{"msg": "hello Razeen"}"// @Failure 400 {string} string "{"msg": "who are you"}"// @Router /hello [get]func HandleHello(c *gin.Context) { who := c.Query("who") if who == "" { c.JSON(http.StatusBadRequest, gin.H{"msg": "who are u?"}) return } c.JSON(http.StatusOK, gin.H{"msg": "hello " + who})}

我們?cè)俅蝧wag init, 運(yùn)行一下。

此時(shí)，該API的相關(guān)描述已經(jīng)生成了，我們點(diǎn)擊Try it out還可以直接測(cè)試該API。

是不是很好用，當(dāng)然這并沒(méi)有結(jié)束，這些注釋字段，我們一個(gè)個(gè)解釋。

這些注釋對(duì)應(yīng)出現(xiàn)在API文檔的位置，我在上圖中已經(jīng)標(biāo)出，這里我們主要詳細(xì)說(shuō)說(shuō)下面參數(shù)：

Tags

Tags 是用來(lái)給API分組的。

Accept

接收的參數(shù)類型，支持表單(mpfd) 和 JSON(json)

Produce

返回的數(shù)據(jù)結(jié)構(gòu)，一般都是json, 其他支持如下表：

Mime Type聲明application/jsonjsontext/xmlxmltext/plainplainhtmlhtmlmultipart/form-datampfdapplication/x-www-form-urlencodedx-www-form-urlencodedapplication/vnd.api+jsonjson-apiapplication/x-json-streamjson-streamapplication/octet-streamoctet-streamimage/pngpngimage/jpegjpegimage/gifgif

Param

參數(shù)，從前往后分別是：

@Param 1.參數(shù)名 2.參數(shù)類型 3.參數(shù)數(shù)據(jù)類型 4.是否必須 5.參數(shù)描述 6.其他屬性

• 1.參數(shù)名參數(shù)名就是我們解釋參數(shù)的名字。
• 2.參數(shù)類型參數(shù)類型主要有三種：path 該類型參數(shù)直接拼接在URL中，如Demo中HandleGetFile：// @Param id path integer true "文件ID" query 該類型參數(shù)一般是組合在URL中的，如Demo中HandleHello// @Param who query string true "人名" formData 該類型參數(shù)一般是POST,PUT方法所用，如Demo中HandleLogin// @Param user formData string true "用戶名" default(admin)
• 3.參數(shù)數(shù)據(jù)類型數(shù)據(jù)類型主要支持一下幾種：string (string)integer (int, uint, uint32, uint64)number (float32)boolean (bool)注意，如果你是上傳文件可以使用file, 但參數(shù)類型一定是formData, 如下：// @Param file formData file true "文件"
• 4.是否是必須表明該參數(shù)是否是必須需要的，必須的在文檔中會(huì)黑體標(biāo)出，測(cè)試時(shí)必須填寫。
• 5.參數(shù)描述就是參數(shù)的一些說(shuō)明
• 6.其他屬性除了上面這些屬性外，我們還可以為該參數(shù)填寫一些額外的屬性，如枚舉，默認(rèn)值，值范圍等。如下：枚舉 // @Param enumstring query string false "string enums" Enums(A, B, C) // @Param enumint query int false "int enums" Enums(1, 2, 3) // @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3) 值添加范圍 // @Param string query string false "string valid" minlength(5) maxlength(10) // @Param int query int false "int valid" mininum(1) maxinum(10) 設(shè)置默認(rèn)值 // @Param default query string false "string default" default(A) 而且這些參數(shù)是可以組合使用的，如：// @Param enumstring query string false "string enums" Enums(A, B, C) default(A) Success

指定成功響應(yīng)的數(shù)據(jù)。格式為：

// @Success 1.HTTP響應(yīng)碼 {2.響應(yīng)參數(shù)類型} 3.響應(yīng)數(shù)據(jù)類型 4.其他描述

• 1.HTTP響應(yīng)碼也就是200，400，500那些。
• 2.響應(yīng)參數(shù)類型 / 3.響應(yīng)數(shù)據(jù)類型返回的數(shù)據(jù)類型，可以是自定義類型，可以是json。自定義類型在平常的使用中，我都會(huì)返回一些指定的模型序列化JSON的數(shù)據(jù)，這時(shí)，就可以這么寫：// @Success 200 {object} main.File 其中，模型直接用包名.模型即可。你會(huì)說(shuō)，假如我返回模型數(shù)組怎么辦？這時(shí)你可以這么寫：// @Success 200 {anrry} main.File json將如你只是返回其他的json數(shù)據(jù)可如下寫：// @Success 200 {string} json ""
• 4.其他描述可以添加一些說(shuō)明。

Failure

? 同Success。

Router

? 指定路由與HTTP方法。格式為：

// @Router /path/to/handle [HTTP方法]

? 不用加基礎(chǔ)路徑哦。

1.1.4. 生成文檔與測(cè)試

其實(shí)上面已經(jīng)穿插的介紹了。

在main.go下運(yùn)行swag init即可生成和更新文檔。

點(diǎn)擊文檔中的Try it out即可測(cè)試。 如果部分API需要登陸，可以Try登陸接口即可。

1.1.5. 優(yōu)化

看到這里，基本可以使用了。但文檔一般只是我們測(cè)試的時(shí)候需要，當(dāng)我的產(chǎn)品上線后，接口文檔是不應(yīng)該給用戶的，而且?guī)в薪涌谖臋n的包也會(huì)大很多(swaggo是直接build到二進(jìn)制里的)。

想要處理這種情況，我們可以在編譯的時(shí)候優(yōu)化一下，如利用build tag來(lái)控制是否編譯文檔。

在main.go聲明swagHandler,并在該參數(shù)不為空時(shí)才加入路由：

package main//...var swagHandler gin.HandlerFuncfunc main(){ // ... if swagHandler != nil { r.GET("/swagger/*any", swagHandler) } //...}

同時(shí),我們將該參數(shù)在另外加了build tag的包中初始化。

// +build docpackage mainimport ( _ "github.com/razeencheng/demo-go/swaggo-gin/docs" ginSwagger "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles")func init() { swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)}

之后我們就可以使用go build -tags "doc"來(lái)打包帶文檔的包，直接go build來(lái)打包不帶文檔的包。

你會(huì)發(fā)現(xiàn)，即使我這么小的Demo,編譯后的大小也要相差19M !

? swaggo-gin git:(master) ? go build? swaggo-gin git:(master) ? ll swaggo-gin-rwxr-xr-x 1 xxx staff 15M Jan 13 00:23 swaggo-gin? swaggo-gin git:(master) ? go build -tags "doc"? swaggo-gin git:(master) ? ll swaggo-gin-rwxr-xr-x 1 xxx staff 34M Jan 13 00:24 swaggo-gin

文章到這里也就結(jié)束了，完整的Demo地址在這里。

相關(guān)鏈接

• Swaggo Github
• Swagger

總結(jié)

以上是生活随笔為你收集整理的apache license 2.0如何使用防止法律纠纷_go语言使用Swaggo详细教程的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。