go swagger

Go 中使用 Swagger 主要目的是为 RESTful API 生成自动化的文档和工具支持，目前有两种流行的工具：go-swagger 和 swag。以下是基于 Go 泛型和最新信息（截至 2025 年 9 月 24 日）的详细讲解，重点介绍 go-swagger 和 swag 的使用方法、步骤和应用场景。内容结合了网络资源中的实践经验，确保实用性。

1. 什么是 Go Swagger？

Swagger 是一个基于 OpenAPI 规范的工具集，用于设计、构建和文档化 RESTful API。go-swagger 和 swag 是 Go 社区的实现：

  • go-swagger: 提供全面的工具集，包括代码生成（服务器、客户端、模型）、文档验证等，适合复杂项目。它支持 OpenAPI 2.0（Swagger 2.0），但暂不支持 3.x。
  • swag: 专注于从 Go 代码注释生成 Swagger 文档，配置简单，适合快速集成，尤其与 Web 框架（如 Gin、Echo）结合使用。

选择建议：swag 适合初学者或小型项目，go-swagger 适合需要生成完整代码或复杂 API 的场景。

2. 安装

安装 go-swagger

1
go install github.com/go-swagger/go-swagger/cmd/swagger@latest

验证安装：

1
swagger version

如果输出版本号，说明安装成功。也可通过二进制文件或 Docker 获取。

安装 swag

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

验证：

1
swag version

3. 使用 swag 生成 Swagger 文档

swag 的核心是基于 Go 注释（godoc 风格）生成 Swagger JSON/YAML 文件，适合与 Web 框架集成。

步骤

  1. 初始化项目
    创建一个 Go 项目，包含 main.go。例如：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    package main

    import (
        "github.com/gin-gonic/gin"
        _ "your_project/docs" // 自动生成的 docs 包
    )

    // @title Simple API
    // @version 1.0
    // @description A sample API
    // @host localhost:8080
    // @BasePath /api/v1
    func main() {
        r := gin.Default()
        r.GET("/ping", func(c *gin.Context) {
            c.JSON(200, gin.H{"message": "pong"})
        })
        r.Run()
    }

  2. 添加注释
    为 API 端点添加 Swagger 注释。示例：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    // @Summary Ping the server
    // @Description Returns a pong message
    // @Tags health
    // @Produce json
    // @Success 200 {string} pong
    // @Router /ping [get]
    func pingHandler(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    }

  3. 生成文档
    运行：

    1
    swag init -g main.go

    这会在项目根目录生成 docs 目录，包含 docs.go 和 swagger.json/swagger.yaml。

  4. 集成 Swagger UI
    使用 swaggo 集成 Swagger UI（以 Gin 为例）：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    import (
        "github.com/gin-gonic/gin"
        ginSwagger "github.com/swaggo/gin-swagger"
        "github.com/swaggo/gin-swagger/swaggerFiles"
    )

    func main() {
        r := gin.Default()
        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
        r.GET("/ping", pingHandler)
        r.Run(":8080")
    }

    访问 http://localhost:8080/swagger/index.html 查看文档。

应用场景

  • 快速原型：适合快速构建 API 并生成文档。
  • 框架集成：与 Gin、Echo 等框架无缝配合。
  • 团队协作：注释驱动的文档便于开发者维护。

4. 使用 go-swagger 生成代码和文档

go-swagger 更强大，适合从 Swagger 规范生成服务器、客户端或验证文档。

步骤

  1. 创建 Swagger 规范文件
    创建 swagger.yaml（或 swagger.json）。示例：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    swagger: "2.0"
    info:
      title: "Todo API"
      description: "A simple Todo API"
      version: "1.0.0"
    host: localhost:8080
    schemes:
      - http
    paths:
      /todos:
        get:
          summary: "List all todos"
          responses:
            "200":
              description: "A list of todos"

  2. 初始化项目
    使用 swagger init 创建基础结构：

    1
    swagger init spec --title "Todo API" --description "A Todo API" --version 1.0.0 --scheme http

    这生成 models、restapi 和 cmd 目录。

  3. 生成代码
    运行：

    1
    2
    swagger generate server -f swagger.yaml
    swagger generate client -f swagger.yaml
    • 生成服务器代码（restapi 目录）。
    • 生成客户端代码（client 目录）。

  4. 实现逻辑
    编辑 restapi/configure_todo.go，实现端点逻辑。例如：

    1
    2
    3
    api.TodosGetHandler = todos.GetHandlerFunc(func(params todos.GetParams) middleware.Responder {
        return todos.NewGetOK().WithPayload([]string{"todo1", "todo2"})
    })

  5. 运行服务器
    安装并运行：

    1
    2
    go install ./cmd/todo-server/
    todo-server

    访问 http://localhost:8080/todos 测试。

  6. 验证和文档
    使用 swagger validate swagger.yaml 检查规范有效性。

应用场景

  • 规范优先开发：从 Swagger 文件生成代码，适合 API 设计先行。
  • 跨语言支持：生成客户端，方便与其他语言集成。
  • 复杂项目：支持多端点、多模型的完整 API 开发。

5. 结合泛型的应用

虽然 Swagger 本身不直接使用 Go 泛型，但可以结合泛型编写更灵活的代码。例如：

  • 泛型响应处理：使用泛型封装 API 响应。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    type Response[T any] struct {
        Data T
        Error error
    }

    func HandleRequest[T any](c *gin.Context) Response[T] {
        var data T
        // 逻辑...
        return Response[T]{Data: data, Error: nil}
    }

    在 Swagger 注释中，描述 Data 的类型。

  • 泛型模型：定义通用模型支持多种类型。

    1
    2
    3
    4
    5
    type Item[T any] struct {
        ID    int
        Value T
    }
    // @Success 200 {object} Item[string]

6. 注意事项

  • 版本兼容：go-swagger 仅支持 OpenAPI 2.0，swag 也主要基于 2.0。
  • 性能：生成代码可能增加编译时间，需权衡。
  • 维护：注释驱动的文档需与代码同步更新，否则失效。
  • 限制：泛型与 Swagger 集成时，需手动调整类型定义。

7. 总结

  • 选择工具：swag 简单快捷，适合快速文档化；go-swagger 功能强大，适合完整开发。
  • 实践建议：从注释驱动（swag）开始，项目复杂后过渡到规范驱动（go-swagger）。
  • 结合泛型：提升代码复用性，尤其在处理响应或模型时。
[up主专用，视频内嵌代码贴在这]