Go 語言 API 文檔利器：絲襪哥（Swagger）保姆級使用指南大揭祕！

咱們都知道在 API 開發中，文檔是必不可少的一環。

swaggo/swag 是一個用於 Go 語言的自動化生成 API 文檔的工具，它可以將代碼註釋轉換爲 Swagger 文檔，方便開發者和用戶理解 API 的使用方法。

本文將詳細介紹 swaggo/swag 的使用方式以及它的特性。

1. 安裝 Swaggo/Swag

先在你的 Go 項目中安裝 swag 命令行工具和 gin-swagger 依賴：

# 安裝 swag 命令行工具
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 格式的文檔文件。生成的文檔可以通過網頁進行查看和測試。主要特性如下：

1. 自動生成 API 文檔：通過掃描代碼中的註釋，將註釋內容轉換爲 OpenAPI 規範的 Swagger 文檔。

2. 靈活的註釋方式：支持豐富的註釋語法，開發者可以在註釋中描述接口的詳細信息，包括請求參數、響應結構等。

3. 內嵌 Swagger UI：生成的 API 文檔可以通過網頁查看，並使用 Swagger UI 直接進行 API 測試。

4. 支持多種 Web 框架：支持常見的 Go Web 框架，如 Gin、Echo、Fiber 等。

5. 定製化：可以通過註釋自定義文檔的內容，包括參數、響應、錯誤代碼等。

3. Swag 的基本使用

3.1 項目結構

爲了更好地演示 swaggo/swag 的使用，假設我們的項目目錄結構如下：

myapp/
├── docs/
├── main.go

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

3.2 在代碼中添加註釋

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

package main

import (
 "github.com/gin-gonic/gin"
 _ "myapp/docs" // 引入 docs 包，以便 swag 自動生成文檔
 swaggerFiles "github.com/swaggo/files"
 ginSwagger "github.com/swaggo/gin-swagger"
 "net/http"
)

// @title Swagger Example API
// @version 1.0
// @description 這是一個簡單的 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()

 // 設置 Swagger 文檔的路由
 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

 // 註冊 API 路由
 api := r.Group("/api/v1")
 {
  api.GET("/hello", helloWorld)
 }

 // 啓動服務
 r.Run(":8080")
}

// @Summary 說你好
// @Description 輸出一個問候信息
// @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 文檔

運行以下命令來生成 Swagger 文檔：

swag init

執行上述命令後，swag 會掃描你的代碼並生成文檔文件，默認會在 docs/ 文件夾下生成 docs.go 和 swagger.json。

3.4 運行應用並查看 Swagger 文檔

啓動應用後，在瀏覽器中訪問 http://localhost:8080/swagger/index.html，即可查看自動生成的 Swagger 文檔。

4. Swag 註釋詳解

swaggo/swag 的註釋語法非常靈活，可以在註釋中詳細描述 API 接口的功能。常用的註釋關鍵字如下：

4.1 基本註釋

• @title：文檔的標題。

• @version：API 的版本。

• @description：對 API 的描述。

• @termsOfService：服務條款的 URL。

• @contact.name、@contact.url、@contact.email：聯繫信息。

• @host：API 的主機地址。

• @BasePath：API 的基礎路徑。

4.2 路由註釋

• @Router：指定接口的 URL 路徑和 HTTP 方法。

• @Summary：接口的簡要描述。

• @Description：接口的詳細描述。

• @Tags：接口的分類標籤。

• @Accept：指定請求的 MIME 類型，例如 json。

• @Produce：指定響應的 MIME 類型，例如 json。

• @Param：描述接口的參數，例如查詢參數、路徑參數、請求體等。

• @Success：描述接口的成功響應。

• @Failure：描述接口的失敗響應。

• @Header：描述響應頭。

• @Security：描述接口的安全性，例如 BasicAuth、APIKey、BearerToken 等。

5. 更高級的特性

5.1 參數註釋

@Param 用於描述接口的請求參數，支持路徑參數、查詢參數、請求體等多種類型。

// @Param id path int true "用戶ID"
// @Param name query string false "用戶名"
// @Param body body models.User true "用戶信息"

• path：路徑參數。

• query：查詢參數。

• body：請求體。

5.2 響應註釋

• @Success 和 @Failure 用於描述接口的成功和失敗響應。

// @Success 200 {object} models.User "成功時返回的用戶信息"
// @Failure 400 {string} string "請求參數錯誤"
// @Failure 404 {string} string "找不到指定的資源"

5.3 安全性

@Security 用於描述 API 的安全機制。

// @Security ApiKeyAuth

6. 運行時動態設置 Swagger 信息

swaggo/swag 生成的 Swagger 文檔是靜態的，但你可以在運行時通過 Go 代碼來動態更新文檔內容。

例如，在特定條件下更改 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. 集成到現有 CI/CD 管道

swaggo/swag 可以輕鬆集成到 CI/CD 管道中，自動生成和驗證 Swagger 文檔。

例如，在 CI 環境中運行 swag init 以確保每次構建的 API 文檔都是最新的。

7.1 在 CI 中自動生成文檔

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

swag init
go test ./...
go build -o myapp

8. 支持多種 Web 框架

swaggo/swag 支持多種常見的 Web 框架，包括：

• Gin: 通過 gin-swagger 集成 Swagger UI。

• Echo: 使用 echo-swagger 集成 Swagger UI。

• Fiber: 使用 fiber-swagger 集成 Swagger UI。

使用方式類似，只需要替換對應框架的包和路由配置。

9. 支持複雜數據結構的註解

swaggo/swag 支持對複雜數據結構進行註解，可以通過 Go 語言的結構體嵌套和註釋來描述複雜的請求體和響應體。

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

9.1 嵌套結構體示例

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 根據用戶ID獲取用戶詳細信息
// @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) {
 // 實現獲取用戶的邏輯
}

• 通過在註釋中使用 {object} User，swaggo/swag 會自動生成該結構體及其嵌套結構體的描述。

10. 自定義註解

swaggo/swag 允許自定義註解來描述 API 的請求和響應，以支持多種不同的業務需求。

可以通過 @Param、@Success、@Failure 等註解來自定義接口的輸入輸出。

10.1 自定義註解示例

// @Summary 創建新用戶
// @Description 使用 JSON 格式的請求體創建一個新用戶
// @Tags user
// @Accept json
// @Produce json
// @Param user body User true "用戶信息"
// @Success 201 {object} User "創建成功返回的用戶信息"
// @Failure 400 {object} string "請求參數錯誤"
// @Failure 500 {object} string "服務器內部錯誤"
// @Router /user [post]
func createUser(c *gin.Context) {
 // 實現創建用戶的邏輯
}

• 通過自定義註解，可以明確指定請求體的格式和結構，以及響應的類型和狀態碼。

11. 分組註解

swaggo/swag 提供了 @Tags 註解來對 API 進行分組。

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

11.1 分組接口示例

// @Summary 登錄接口
// @Tags auth
// @Accept json
// @Produce json
// @Param credentials body LoginRequest true "登錄憑據"
// @Success 200 {string} string "登錄成功"
// @Failure 401 {string} string "認證失敗"
// @Router /login [post]
func login(c *gin.Context) {
 // 實現登錄邏輯
}

在 Swagger UI 中，API 會按標籤進行分組，例如將所有用戶相關的接口放在 "user" 標籤下，將所有身份驗證相關的接口放在 "auth" 標籤下。

12. 支持多文件註解

在一個大型的項目中，API 可能會被拆分到多個文件中。swaggo/swag 支持多文件註解，只要在每個文件中包含註釋，swag init 命令就會掃描整個項目中的註釋並生成文檔。

12.1 項目結構

myapp/
├── main.go
├── handlers/
│   ├── user.go
│   └── auth.go
└── docs/

在 user.go 和 auth.go 中分別添加註解，swag init 命令會自動掃描併合並這些文件中的註解信息。

13. 支持定製 Swagger 文檔

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

你可以通過註解和配置文件來更改文檔內容，例如指定 API 的版本、標題、描述、許可證等。

13.1 自定義文檔信息

通過在 main.go 文件中使用註解設置全局文檔信息：

// @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 安全性設置

swaggo/swag 支持爲 API 設置安全性，例如 OAuth2、API Key、Basic Auth 等。

可以通過註解指定 API 的安全機制。

14.1 設置 Basic Auth

// @Security BasicAuth
// @Summary 受保護的接口
// @Tags protected
// @Success 200 {string} string "成功"
// @Router /protected [get]
func protectedEndpoint(c *gin.Context) {
 // 實現邏輯
}

15. 請求和響應示例

在文檔中添加請求和響應的示例數據，使接口更加直觀。可以通過註解提供示例值。

15.1 添加示例數據

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

16. 註解支持多種類型

• int、string、bool 等基本類型。

• object：用於描述嵌套結構體。

• array：用於描述數組類型，例如 []string。

• file：用於文件上傳接口。

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

17. 支持響應頭信息

通過註解添加自定義的響應頭信息，增強接口描述。

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

18. 接口描述的豐富性

swaggo/swag 的註解非常靈活，可以爲接口添加詳細的描述，包括請求參數的類型、必填性、默認值、取值範圍等，幫助開發者更好地理解和使用 API。

19. 多語言支持

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

Swagger-UI 可以根據瀏覽器設置自動適配不同的語言界面，這爲國際化項目提供了便利。

20. 使用自定義模板

swaggo/swag 支持使用自定義模板來生成 Swagger 文檔。

通過自定義模板，你可以根據自己的需求，改變 Swagger 文檔的結構和樣式。

自定義模板爲那些希望定製化 API 文檔風格的團隊提供了靈活性。

20.1 自定義模板示例

創建一個自定義模板文件，例如 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}}
  }
}

通過 swag 工具使用自定義模板：

swag init --template template/custom.tmpl

21. 中間件支持

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

21.1 在 Gin 中使用中間件

在 Gin 中使用身份驗證中間件保護 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. 支持全局參數

有時你的 API 需要在每個請求中包含相同的全局參數，例如 Authorization 頭部或者語言參數。swaggo/swag 支持在生成的文檔中添加全局參數定義。

22.1 定義全局參數

通過註釋爲文檔添加全局參數：

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization

• 通過 @securityDefinitions 註解定義一個全局的 API 密鑰認證方式，所有需要此認證的路由都可以共享這個定義。

23. 使用 YAML 格式文檔

默認情況下，swaggo/swag 會生成 JSON 格式的 Swagger 文檔。

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

23.1 生成 YAML 文檔

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

swag init --output docs --format yaml

生成的 YAML 文件通常會放在 docs/swagger.yaml 中，可以在應用啓動時讀取這個文件，提供 API 文檔服務。

24. 自定義請求 / 響應示例和枚舉值

通過註解，你可以在文檔中詳細定義請求和響應示例數據，並且爲參數指定枚舉值。

24.1 定義枚舉值

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

• 使用 Enums 關鍵字指定參數的可選值。

24.2 添加請求示例

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

• 使用 example 關鍵字爲請求體添加示例數據。

這樣可以在每次提交代碼後，自動更新文檔並運行測試。

25. 支持多版本 API 文檔

對於一個大型應用來說，支持多版本的 API 是非常重要的。

swaggo/swag 可以通過不同的 @BasePath 註解來區分不同版本的 API。

25.1 定義多版本 API

// @BasePath /api/v1
// @BasePath /api/v2

在項目中可以定義多個版本的 API，每個版本對應不同的 BasePath，以在 Swagger 文檔中清晰地展示不同版本的接口。

26. 可擴展性：支持自定義 Swagger 插件

如果你對 swaggo/swag 的默認行爲不滿意，可以開發自定義插件來擴展 Swagger 文檔的生成過程。這使得 swaggo/swag 成爲一個高度可擴展的文檔生成工具。

27. 生成離線文檔

swaggo/swag 生成的 Swagger 文檔（swagger.json 或 swagger.yaml）可以通過 swagger-ui 工具生成離線文檔，方便你在無網絡環境下使用。

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

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

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

最後

這絕對算得上是保姆級的使用指南了吧！

通過 swaggo/swag，你可以快速爲 Go 項目生成專業的、豐富的 API 文檔，極大地提高開發效率和文檔質量。

趕緊使用起來吧！

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/DiTgvTW7Z_o4UEmlIikB9g