go install github.com/swaggo/swag/cmd/swag@latest

# 安裝 gin-swagger 和 swagger 文件的依賴
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2. Swag 的基本特性

swaggo/swag 可以解析代碼中的注釋，并將其生成 Swagger 格式的文檔文件。生成的文檔可以通過(guò)網(wǎng)頁(yè)進(jìn)行查看和測(cè)試。主要特性如下：

  1. 自動(dòng)生成 API 文檔：通過(guò)掃描代碼中的注釋，將注釋內(nèi)容轉(zhuǎn)換為 OpenAPI 規(guī)范的 Swagger 文檔。
  2. 靈活的注釋方式：支持豐富的注釋語(yǔ)法，開發(fā)者可以在注釋中描述接口的詳細(xì)信息，包括請(qǐng)求參數(shù)、響應(yīng)結(jié)構(gòu)等。
  3. 內(nèi)嵌 Swagger UI：生成的 API 文檔可以通過(guò)網(wǎng)頁(yè)查看，并使用 Swagger UI 直接進(jìn)行 API 測(cè)試。
  4. 支持多種 Web 框架：支持常見(jiàn)的 Go Web 框架，如 Gin、Echo、Fiber 等。
  5. 定制化：可以通過(guò)注釋自定義文檔的內(nèi)容，包括參數(shù)、響應(yīng)、錯(cuò)誤代碼等。

3. Swag 的基本使用

3.1 項(xiàng)目結(jié)構(gòu)

為了更好地演示 swaggo/swag 的使用，假設(shè)我們的項(xiàng)目目錄結(jié)構(gòu)如下：

myapp/

├── docs/

├── main.go

其中，docs/ 文件夾是生成的 Swagger 文檔將要存放的目錄。

3.2 在代碼中添加注釋

在你的 Go 代碼中，使用 swag 的注釋格式為 API 接口添加注釋。以下是一個(gè)使用 Gin 框架的示例，main.go 文件中的代碼如下：

package main



import (

 "github.com/gin-gonic/gin"

 _ "myapp/docs" // 引入 docs 包，以便 swag 自動(dòng)生成文檔

 swaggerFiles "github.com/swaggo/files"

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

 "net/http"

)



// @title Swagger Example API

// @version 1.0

// @description 這是一個(gè)簡(jiǎn)單的 API 文檔示例

// @termsOfService http://swagger.io/terms/



// @contact.name API Support

// @contact.url http://www.swagger.io/support

// @contact.email support@swagger.io



// @host localhost:8080

// @BasePath /api/v1



func main() {

 r := gin.Default()



 // 設(shè)置 Swagger 文檔的路由

 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))



 // 注冊(cè) API 路由

 api := r.Group("/api/v1")

 {

  api.GET("/hello", helloWorld)

 }



 // 啟動(dòng)服務(wù)

 r.Run(":8080")

}



// @Summary 說(shuō)你好

// @Description 輸出一個(gè)問(wèn)候信息

// @Tags hello

// @Accept json

// @Produce json

// @Success 200 {string} string "success"

// @Router /hello [get]

func helloWorld(c *gin.Context) {

 c.JSON(http.StatusOK, gin.H{

  "message": "Hello, world!",

 })

}

3.3 生成 Swagger 文檔

運(yùn)行以下命令來(lái)生成 Swagger 文檔：

swag init

執(zhí)行上述命令后，swag 會(huì)掃描你的代碼并生成文檔文件，默認(rèn)會(huì)在 docs/ 文件夾下生成 docs.go 和 swagger.json。

3.4 運(yùn)行應(yīng)用并查看 Swagger 文檔

啟動(dòng)應(yīng)用后，在瀏覽器中訪問(wèn) http://localhost:8080/swagger/index.html，即可查看自動(dòng)生成的 Swagger 文檔。

4. Swag 注釋詳解

swaggo/swag 的注釋語(yǔ)法非常靈活，可以在注釋中詳細(xì)描述 API 接口的功能。常用的注釋關(guān)鍵字如下：

4.1 基本注釋

4.2 路由注釋

5. 更高級(jí)的特性

5.1 參數(shù)注釋

@Param 用于描述接口的請(qǐng)求參數(shù)，支持路徑參數(shù)、查詢參數(shù)、請(qǐng)求體等多種類型。

// @Param id path int true "用戶ID"

// @Param name query string false "用戶名"

// @Param body body models.User true "用戶信息"

5.2 響應(yīng)注釋

// @Success 200 {object} models.User "成功時(shí)返回的用戶信息"

// @Failure 400 {string} string "請(qǐng)求參數(shù)錯(cuò)誤"

// @Failure 404 {string} string "找不到指定的資源"

5.3 安全性

@Security 用于描述 API 的安全機(jī)制。

// @Security ApiKeyAuth

6. 運(yùn)行時(shí)動(dòng)態(tài)設(shè)置 Swagger 信息

swaggo/swag?生成的 Swagger 文檔是靜態(tài)的，但你可以在運(yùn)行時(shí)通過(guò) Go 代碼來(lái)動(dòng)態(tài)更新文檔內(nèi)容。

例如，在特定條件下更改 Swagger 信息：

import "github.com/swaggo/swag"



swag.SwaggerInfo.Title = "My Dynamic API"

swag.SwaggerInfo.Host = "api.example.com"

swag.SwaggerInfo.Version = "2.0"

swag.SwaggerInfo.BasePath = "/v2"

7. 集成到現(xiàn)有 CI/CD 管道

swaggo/swag 可以輕松集成到 CI/CD 管道中，自動(dòng)生成和驗(yàn)證 Swagger 文檔。

例如，在 CI 環(huán)境中運(yùn)行 swag init 以確保每次構(gòu)建的 API 文檔都是最新的。

7.1 在 CI 中自動(dòng)生成文檔

可以在 CI/CD 腳本中添加以下命令：

swag init

go test ./...

go build -o myapp

8. 支持多種 Web 框架

swaggo/swag 支持多種常見(jiàn)的 Web 框架，包括：

使用方式類似，只需要替換對(duì)應(yīng)框架的包和路由配置。

9. 支持復(fù)雜數(shù)據(jù)結(jié)構(gòu)的注解

swaggo/swag 支持對(duì)復(fù)雜數(shù)據(jù)結(jié)構(gòu)進(jìn)行注解，可以通過(guò) Go 語(yǔ)言的結(jié)構(gòu)體嵌套和注釋來(lái)描述復(fù)雜的請(qǐng)求體和響應(yīng)體。

這個(gè)特性非常適合生成包含嵌套 JSON 的 API 文檔。

9.1 嵌套結(jié)構(gòu)體示例

type Address struct {

 Street  string json:"street"
 City    string json:"city"
 ZipCode string json:"zip_code"
}

type User struct {
 ID      int      json:"id"
 Name    string   json:"name"
 Email   string   json:"email"
 Address Address  json:"address"
}

// @Summary 獲取用戶信息
// @Description 根據(jù)用戶ID獲取用戶詳細(xì)信息
// @Tags user
// @Produce json
// @Param id path int true "用戶ID"
// @Success 200 {object} User "返回用戶信息"
// @Failure 404 {object} string "用戶未找到"
// @Router /user/{id} [get]
func getUser(c *gin.Context) {
 // 實(shí)現(xiàn)獲取用戶的邏輯
}

10. 自定義注解

swaggo/swag 允許自定義注解來(lái)描述 API 的請(qǐng)求和響應(yīng)，以支持多種不同的業(yè)務(wù)需求。

可以通過(guò) @Param、@Success、@Failure 等注解來(lái)自定義接口的輸入輸出。

10.1 自定義注解示例

// @Summary 創(chuàng)建新用戶

// @Description 使用 JSON 格式的請(qǐng)求體創(chuàng)建一個(gè)新用戶

// @Tags user

// @Accept json

// @Produce json

// @Param user body User true "用戶信息"

// @Success 201 {object} User "創(chuàng)建成功返回的用戶信息"

// @Failure 400 {object} string "請(qǐng)求參數(shù)錯(cuò)誤"

// @Failure 500 {object} string "服務(wù)器內(nèi)部錯(cuò)誤"

// @Router /user [post]

func createUser(c *gin.Context) {

 // 實(shí)現(xiàn)創(chuàng)建用戶的邏輯

}

11. 分組注解

swaggo/swag 提供了 @Tags 注解來(lái)對(duì) API 進(jìn)行分組。

使用分組功能可以讓 API 文檔更加清晰，便于查找和分類。

11.1 分組接口示例

// @Summary 登錄接口

// @Tags auth

// @Accept json

// @Produce json

// @Param credentials body LoginRequest true "登錄憑據(jù)"

// @Success 200 {string} string "登錄成功"

// @Failure 401 {string} string "認(rèn)證失敗"

// @Router /login [post]

func login(c *gin.Context) {

 // 實(shí)現(xiàn)登錄邏輯

}

在 Swagger UI 中，API 會(huì)按標(biāo)簽進(jìn)行分組，例如將所有用戶相關(guān)的接口放在 “user” 標(biāo)簽下，將所有身份驗(yàn)證相關(guān)的接口放在 “auth” 標(biāo)簽下。

12. 支持多文件注解

在一個(gè)大型的項(xiàng)目中，API 可能會(huì)被拆分到多個(gè)文件中。swaggo/swag 支持多文件注解，只要在每個(gè)文件中包含注釋，swag init 命令就會(huì)掃描整個(gè)項(xiàng)目中的注釋并生成文檔。

12.1 項(xiàng)目結(jié)構(gòu)

myapp/

├── main.go

├── handlers/

│   ├── user.go

│   └── auth.go

└── docs/

在 user.go 和 auth.go 中分別添加注解，swag init 命令會(huì)自動(dòng)掃描并合并這些文件中的注解信息。

13. 支持定制 Swagger 文檔

swaggo/swag 允許你自定義生成的 Swagger 文檔，包括 swagger.json 和 swagger.yaml。

你可以通過(guò)注解和配置文件來(lái)更改文檔內(nèi)容，例如指定 API 的版本、標(biāo)題、描述、許可證等。

13.1 自定義文檔信息

通過(guò)在 main.go 文件中使用注解設(shè)置全局文檔信息：

// @title My API

// @version 1.0

// @description 這是我的 API 文檔。

// @termsOfService http://example.com/terms/



// @contact.name API Support

// @contact.url http://www.example.com/support

// @contact.email support@example.com



// @license.name MIT

// @license.url https://opensource.org/licenses/MIT



// @host localhost:8080

// @BasePath /api/v1

14. 支持 API 安全性設(shè)置

swaggo/swag 支持為 API 設(shè)置安全性，例如 OAuth2、API Key、Basic Auth 等。

可以通過(guò)注解指定 API 的安全機(jī)制。

14.1 設(shè)置 Basic Auth

// @Security BasicAuth

// @Summary 受保護(hù)的接口

// @Tags protected

// @Success 200 {string} string "成功"

// @Router /protected [get]

func protectedEndpoint(c *gin.Context) {

 // 實(shí)現(xiàn)邏輯

}

15. 請(qǐng)求和響應(yīng)示例

在文檔中添加請(qǐng)求和響應(yīng)的示例數(shù)據(jù)，使接口更加直觀。可以通過(guò)注解提供示例值。

15.1 添加示例數(shù)據(jù)

// @Param user body User true "用戶信息" default({"name": "John Doe", "email": "john@example.com"})

// @Success 200 {object} User "創(chuàng)建成功返回的用戶信息" example({"id": 1, "name": "John Doe", "email": "john@example.com"})

16. 注解支持多種類型

// @Param file formData file true "文件上傳"

17. 支持響應(yīng)頭信息

通過(guò)注解添加自定義的響應(yīng)頭信息，增強(qiáng)接口描述。

// @Header 200 {string} X-Token "服務(wù)器返回的 Token"

18. 接口描述的豐富性

swaggo/swag 的注解非常靈活，可以為接口添加詳細(xì)的描述，包括請(qǐng)求參數(shù)的類型、必填性、默認(rèn)值、取值范圍等，幫助開發(fā)者更好地理解和使用 API。

19. 多語(yǔ)言支持

雖然 swaggo/swag 本身沒(méi)有直接提供多語(yǔ)言支持，但生成的文檔可以在 Swagger-UI 中顯示不同的語(yǔ)言。

Swagger-UI 可以根據(jù)瀏覽器設(shè)置自動(dòng)適配不同的語(yǔ)言界面，這為國(guó)際化項(xiàng)目提供了便利。

20. 使用自定義模板

swaggo/swag 支持使用自定義模板來(lái)生成 Swagger 文檔。

通過(guò)自定義模板，你可以根據(jù)自己的需求，改變 Swagger 文檔的結(jié)構(gòu)和樣式。

自定義模板為那些希望定制化 API 文檔風(fēng)格的團(tuán)隊(duì)提供了靈活性。

20.1 自定義模板示例

創(chuàng)建一個(gè)自定義模板文件，例如 template/custom.tmpl：

{

  "swagger": "2.0",

  "info": {

    "title": "{{.Title}}",

    "description": "{{.Description}}",

    "version": "{{.Version}}"

  },

  "paths": {

    {{range .Paths}}

    "{{.Path}}": {

      "get": {

        "summary": "{{.Summary}}",

        "operationId": "{{.OperationID}}",

        "parameters": [{{range .Parameters}}{{.Name}}: {{.Type}}{{end}}]

      }

    }

    {{end}}

  }

}

通過(guò) swag 工具使用自定義模板：
swag init --template template/custom.tmpl

21. 中間件支持

swaggo/swag 生成的文檔可以與各種中間件集成，例如身份驗(yàn)證、CORS（跨域資源共享）、速率限制等。這使得你可以通過(guò)中間件控制對(duì) Swagger 文檔的訪問(wèn)權(quán)限。

21.1 在 Gin 中使用中間件

在 Gin 中使用身份驗(yàn)證中間件保護(hù) Swagger 文檔：

authMiddleware := func(c *gin.Context) {

 token := c.GetHeader("Authorization")

 if token != "expected-token" {

  c.AbortWithStatus(http.StatusUnauthorized)

  return

 }

 c.Next()

}



r := gin.Default()

r.GET("/swagger/*any", authMiddleware, ginSwagger.WrapHandler(swaggerFiles.Handler))

22. 支持全局參數(shù)

有時(shí)你的 API 需要在每個(gè)請(qǐng)求中包含相同的全局參數(shù)，例如 Authorization 頭部或者語(yǔ)言參數(shù)。swaggo/swag 支持在生成的文檔中添加全局參數(shù)定義。

22.1 定義全局參數(shù)

通過(guò)注釋為文檔添加全局參數(shù)：

// @securityDefinitions.apikey ApiKeyAuth

// @in header

// @name Authorization

23. 使用 YAML 格式文檔

默認(rèn)情況下，swaggo/swag 會(huì)生成 JSON 格式的 Swagger 文檔。

但是，如果你更喜歡 YAML 格式，也可以生成 YAML 格式的文檔。你只需要修改代碼來(lái)支持從 swagger.yaml 讀取數(shù)據(jù)。

23.1 生成 YAML 文檔

通過(guò) swag 工具可以生成 YAML 格式的文檔：

swag init --output docs --format yaml

生成的 YAML 文件通常會(huì)放在 docs/swagger.yaml 中，可以在應(yīng)用啟動(dòng)時(shí)讀取這個(gè)文件，提供 API 文檔服務(wù)。

24. 自定義請(qǐng)求/響應(yīng)示例和枚舉值

通過(guò)注解，你可以在文檔中詳細(xì)定義請(qǐng)求和響應(yīng)示例數(shù)據(jù)，并且為參數(shù)指定枚舉值。

24.1 定義枚舉值

// @Param status query string true "訂單狀態(tài)" Enums(pending, paid, shipped)

24.2 添加請(qǐng)求示例

// @Param user body User true "用戶信息" example({"name": "John Doe", "email": "john@example.com"})

這樣可以在每次提交代碼后，自動(dòng)更新文檔并運(yùn)行測(cè)試。

25. 支持多版本 API 文檔

對(duì)于一個(gè)大型應(yīng)用來(lái)說(shuō)，支持多版本的 API 是非常重要的。

swaggo/swag 可以通過(guò)不同的 @BasePath 注解來(lái)區(qū)分不同版本的 API。

25.1 定義多版本 API

// @BasePath /api/v1

// @BasePath /api/v2

在項(xiàng)目中可以定義多個(gè)版本的 API，每個(gè)版本對(duì)應(yīng)不同的 BasePath，以在 Swagger 文檔中清晰地展示不同版本的接口。

26. 可擴(kuò)展性：支持自定義 Swagger 插件

如果你對(duì) swaggo/swag 的默認(rèn)行為不滿意，可以開發(fā)自定義插件來(lái)擴(kuò)展 Swagger 文檔的生成過(guò)程。這使得 swaggo/swag 成為一個(gè)高度可擴(kuò)展的文檔生成工具。

27. 生成離線文檔

swaggo/swag 生成的 Swagger 文檔（swagger.json 或 swagger.yaml）可以通過(guò) swagger-ui 工具生成離線文檔，方便你在無(wú)網(wǎng)絡(luò)環(huán)境下使用。

27.1 使用 Swagger-UI 生成離線文檔

你可以使用 Swagger-UI 官方提供的工具，將生成的 swagger.json 或 swagger.yaml 嵌入到靜態(tài) HTML 文件中，形成離線可訪問(wèn)的文檔。

swagger-ui-dist/swagger-ui-bundle.js swagger.json > index.html

最后

這絕對(duì)算得上是保姆級(jí)的使用指南了吧！

通過(guò)?swaggo/swag，你可以快速為 Go 項(xiàng)目生成專業(yè)的、豐富的 API 文檔，極大地提高開發(fā)效率和文檔質(zhì)量。

趕緊使用起來(lái)吧！

在我封裝的框架中，生成的 API 文檔使用的正是 swaggo/swag。

文章轉(zhuǎn)自微信公眾號(hào)@程序員新亮

上一篇：

產(chǎn)品經(jīng)理應(yīng)該掌握的ChatGPT API知識(shí)之開始使用

下一篇：

使用gin搭建api后臺(tái)系統(tǒng)之跨域問(wèn)題
#你可能也喜歡這些API文章!

我們有何不同？

API服務(wù)商零注冊(cè)

多API并行試用

數(shù)據(jù)驅(qū)動(dòng)選型，提升決策效率

查看全部API→
??

熱門場(chǎng)景實(shí)測(cè)，選對(duì)API

#AI文本生成大模型API

對(duì)比大模型API的內(nèi)容創(chuàng)意新穎性、情感共鳴力、商業(yè)轉(zhuǎn)化潛力

25個(gè)渠道
一鍵對(duì)比試用API 限時(shí)免費(fèi)

#AI深度推理大模型API

對(duì)比大模型API的邏輯推理準(zhǔn)確性、分析深度、可視化建議合理性

10個(gè)渠道
一鍵對(duì)比試用API 限時(shí)免費(fèi)