Golang实现Swagger API的最佳实践

我已经使用了最后的 swag。

在Go语言中，生成Swagger API文档的最佳实践是使用swaggo/swag工具，它能够直接从Go源代码的注释生成Swagger 2.0规范。以下是具体实现步骤和示例代码：

1. 安装swag工具

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

2. 在Go代码中添加Swagger注释

// main.go
package main

import (
    "github.com/gin-gonic/gin"
    _ "your-project/docs" // 导入生成的docs包
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

// @title User API
// @version 1.0
// @description 用户管理API
// @host localhost:8080
// @BasePath /api/v1
func main() {
    r := gin.Default()
    
    // 添加Swagger路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
    r.Run(":8080")
}

// user.go
package main

// User 用户模型
type User struct {
    ID   int    `json:"id" example:"1"`
    Name string `json:"name" example:"张三"`
}

// GetUser 获取用户信息
// @Summary 获取用户
// @Description 根据ID获取用户信息
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} User
// @Failure 404 {object} map[string]string
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // 处理逻辑
}

// CreateUser 创建用户
// @Summary 创建用户
// @Description 创建新用户
// @Tags users
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 201 {object} User
// @Failure 400 {object} map[string]string
// @Router /users [post]
func CreateUser(c *gin.Context) {
    // 处理逻辑
}

3. 生成Swagger文档

# 在项目根目录执行
swag init

4. 集成到路由框架

// 对于Gin框架（如上例）
// 对于Echo框架：
import (
    echoSwagger "github.com/swaggo/echo-swagger"
)

e.GET("/swagger/*", echoSwagger.WrapHandler)

// 对于标准库net/http：
import (
    "net/http"
    httpSwagger "github.com/swaggo/http-swagger"
)

http.Handle("/swagger/", httpSwagger.WrapHandler)

5. 验证生成结果

执行swag init后会在项目根目录生成docs文件夹，包含：

• docs.go：Swagger规范Go代码
• swagger.json：Swagger JSON规范
• swagger.yaml：Swagger YAML规范

访问http://localhost:8080/swagger/index.html即可查看交互式API文档。

6. 关键注释标签说明

• @title：API标题
• @version：API版本
• @description：API描述
• @Accept/@Produce：请求/响应类型
• @Param：参数定义
• @Success/@Failure：响应状态
• @Router：路由定义
• @Tags：API分组标签

7. 自动化集成示例

// Makefile
.PHONY: swagger
swagger:
    swag init --parseDependency --parseInternal

// 在CI/CD流水线中添加
// - run: make swagger
// - run: go build ./...

swaggo/swag是目前Go生态中最成熟、维护最活跃的Swagger生成工具，支持Gin、Echo、Beego等主流框架，能够自动同步代码和文档，确保API文档的实时准确性。