企業工商數據API用哪種？
你可能也喜歡這些API文章!
swaggo/swag 可以解析代碼中的注釋，并將其生成 Swagger 格式的文檔文件。生成的文檔可以通過網頁進行查看和測試。主要特性如下：
為了更好地演示 swaggo/swag 的使用，假設我們的項目目錄結構如下：
myapp/
├── docs/
├── main.go其中，docs/ 文件夾是生成的 Swagger 文檔將要存放的目錄。
在你的 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!",
})
}運行以下命令來生成 Swagger 文檔：
swag init執行上述命令后，swag 會掃描你的代碼并生成文檔文件，默認會在 docs/ 文件夾下生成 docs.go 和 swagger.json。
啟動應用后，在瀏覽器中訪問 http://localhost:8080/swagger/index.html，即可查看自動生成的 Swagger 文檔。
swaggo/swag 的注釋語法非常靈活，可以在注釋中詳細描述 API 接口的功能。常用的注釋關鍵字如下：
json。json。@Param 用于描述接口的請求參數，支持路徑參數、查詢參數、請求體等多種類型。
// @Param id path int true "用戶ID"
// @Param name query string false "用戶名"
// @Param body body models.User true "用戶信息"path：路徑參數。query：查詢參數。body：請求體。// @Success 200 {object} models.User "成功時返回的用戶信息"
// @Failure 400 {string} string "請求參數錯誤"
// @Failure 404 {string} string "找不到指定的資源"@Security 用于描述 API 的安全機制。
// @Security ApiKeyAuthswaggo/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"swaggo/swag 可以輕松集成到 CI/CD 管道中，自動生成和驗證 Swagger 文檔。
例如，在 CI 環境中運行 swag init 以確保每次構建的 API 文檔都是最新的。
可以在 CI/CD 腳本中添加以下命令：
swag init
go test ./...
go build -o myappswaggo/swag 支持多種常見的 Web 框架，包括：
gin-swagger 集成 Swagger UI。echo-swagger 集成 Swagger UI。fiber-swagger 集成 Swagger UI。使用方式類似，只需要替換對應框架的包和路由配置。
swaggo/swag 支持對復雜數據結構進行注解，可以通過 Go 語言的結構體嵌套和注釋來描述復雜的請求體和響應體。
這個特性非常適合生成包含嵌套 JSON 的 API 文檔。
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 會自動生成該結構體及其嵌套結構體的描述。swaggo/swag 允許自定義注解來描述 API 的請求和響應，以支持多種不同的業務需求。
可以通過 @Param、@Success、@Failure 等注解來自定義接口的輸入輸出。
// @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) {
// 實現創建用戶的邏輯
}swaggo/swag 提供了 @Tags 注解來對 API 進行分組。
使用分組功能可以讓 API 文檔更加清晰，便于查找和分類。
// @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” 標簽下。
在一個大型的項目中，API 可能會被拆分到多個文件中。swaggo/swag 支持多文件注解，只要在每個文件中包含注釋，swag init 命令就會掃描整個項目中的注釋并生成文檔。
myapp/
├── main.go
├── handlers/
│ ├── user.go
│ └── auth.go
└── docs/在 user.go 和 auth.go 中分別添加注解，swag init 命令會自動掃描并合并這些文件中的注解信息。
swaggo/swag 允許你自定義生成的 Swagger 文檔，包括 swagger.json 和 swagger.yaml。
你可以通過注解和配置文件來更改文檔內容，例如指定 API 的版本、標題、描述、許可證等。
通過在 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/v1swaggo/swag 支持為 API 設置安全性，例如 OAuth2、API Key、Basic Auth 等。
可以通過注解指定 API 的安全機制。
// @Security BasicAuth
// @Summary 受保護的接口
// @Tags protected
// @Success 200 {string} string "成功"
// @Router /protected [get]
func protectedEndpoint(c *gin.Context) {
// 實現邏輯
}在文檔中添加請求和響應的示例數據，使接口更加直觀。可以通過注解提供示例值。
// @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"})int、string、bool 等基本類型。object**：用于描述嵌套結構體。array**：用于描述數組類型，例如 []string。file**：用于文件上傳接口。// @Param file formData file true "文件上傳"通過注解添加自定義的響應頭信息，增強接口描述。
// @Header 200 {string} X-Token "服務器返回的 Token"swaggo/swag 的注解非常靈活，可以為接口添加詳細的描述，包括請求參數的類型、必填性、默認值、取值范圍等，幫助開發者更好地理解和使用 API。
雖然 swaggo/swag 本身沒有直接提供多語言支持，但生成的文檔可以在 Swagger-UI 中顯示不同的語言。
Swagger-UI 可以根據瀏覽器設置自動適配不同的語言界面，這為國際化項目提供了便利。
swaggo/swag 支持使用自定義模板來生成 Swagger 文檔。
通過自定義模板，你可以根據自己的需求，改變 Swagger 文檔的結構和樣式。
自定義模板為那些希望定制化 API 文檔風格的團隊提供了靈活性。
創建一個自定義模板文件，例如 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.tmplswaggo/swag 生成的文檔可以與各種中間件集成，例如身份驗證、CORS（跨域資源共享）、速率限制等。這使得你可以通過中間件控制對 Swagger 文檔的訪問權限。
在 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))有時你的 API 需要在每個請求中包含相同的全局參數，例如 Authorization 頭部或者語言參數。swaggo/swag 支持在生成的文檔中添加全局參數定義。
通過注釋為文檔添加全局參數：
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization@securityDefinitions 注解定義一個全局的 API 密鑰認證方式，所有需要此認證的路由都可以共享這個定義。默認情況下，swaggo/swag 會生成 JSON 格式的 Swagger 文檔。
但是，如果你更喜歡 YAML 格式，也可以生成 YAML 格式的文檔。你只需要修改代碼來支持從 swagger.yaml 讀取數據。
通過 swag 工具可以生成 YAML 格式的文檔：
swag init --output docs --format yaml生成的 YAML 文件通常會放在 docs/swagger.yaml 中，可以在應用啟動時讀取這個文件，提供 API 文檔服務。
通過注解，你可以在文檔中詳細定義請求和響應示例數據，并且為參數指定枚舉值。
// @Param status query string true "訂單狀態" Enums(pending, paid, shipped)Enums 關鍵字指定參數的可選值。// @Param user body User true "用戶信息" example({"name": "John Doe", "email": "john@example.com"})example 關鍵字為請求體添加示例數據。這樣可以在每次提交代碼后，自動更新文檔并運行測試。
對于一個大型應用來說，支持多版本的 API 是非常重要的。
swaggo/swag 可以通過不同的 @BasePath 注解來區分不同版本的 API。
// @BasePath /api/v1
// @BasePath /api/v2在項目中可以定義多個版本的 API，每個版本對應不同的 BasePath，以在 Swagger 文檔中清晰地展示不同版本的接口。
如果你對 swaggo/swag 的默認行為不滿意，可以開發自定義插件來擴展 Swagger 文檔的生成過程。這使得 swaggo/swag 成為一個高度可擴展的文檔生成工具。
swaggo/swag 生成的 Swagger 文檔（swagger.json 或 swagger.yaml）可以通過 swagger-ui 工具生成離線文檔，方便你在無網絡環境下使用。
你可以使用 Swagger-UI 官方提供的工具，將生成的 swagger.json 或 swagger.yaml 嵌入到靜態 HTML 文件中，形成離線可訪問的文檔。
swagger-ui-dist/swagger-ui-bundle.js swagger.json > index.html這絕對算得上是保姆級的使用指南了吧！
通過?swaggo/swag，你可以快速為 Go 項目生成專業的、豐富的 API 文檔，極大地提高開發效率和文檔質量。
趕緊使用起來吧！
在我封裝的框架中，生成的 API 文檔使用的正是 swaggo/swag。
文章轉自微信公眾號@程序員新亮
