2. 编写 API 注释

在你的 Go 代码中，使用特定格式的注释来描述 API 的各个部分。swaggo 工具会读取这些注释并生成 Swagger 文档。

2.1 项目入口文件

在项目入口文件（通常是 main.go）中，为项目整体添加注释，包括 API 版本、标题、描述等信息。

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    _ "your_project/docs"
)

// @title Example API
// @version 1.0
// @description This is a sample server for a pet store.
// @termsOfService //example.com/terms/
// @contact.name API Support
// @contact.url //example.com/support
// @contact.email support@example.com
// @license.name Apache 2.0
// @license.url apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /

func main() {
    r := gin.Default()

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

    // 注册路由
    r.GET("/pet/:id", GetPetByID)

    r.Run(":8080")
}

2.2 为 API 路由添加注释

接下来，为每个 API 路由添加详细的注释，包括请求参数、响应格式、状态码等信息。

// GetPetByID godoc
// @Summary Get a pet by ID
// @Description Get pet details by ID
// @Tags pets
// @Accept  json
// @Produce  json
// @Param   id      path    int     true        "Pet ID"
// @Success 200 {object} Pet
// @Failure 400 {object} HTTPError
// @Failure 404 {object} HTTPError
// @Router /pet/{id} [get]
func GetPetByID(c *gin.Context) {
    // 处理请求的代码
}

在这段代码中：

• @Summary 描述了 API 的简要信息。
• @Description 提供了更详细的描述。
• @Tags 用于将 API 分组。
• @Accept 和 @Produce 表示 API 接受和返回的数据格式。
• @Param 描述了路径、查询、头信息或请求体中的参数。
• @Success 和 @Failure 描述了不同状态码下的响应格式。
• @Router 指定了路由路径和方法。

3. 生成 Swagger 文档

在代码编写完成后，使用 swaggo 工具生成 Swagger 文档。

这个命令会在项目根目录生成一个 docs 文件夹，其中包含 Swagger 文档的相关信息。

4. 在项目中集成 Swagger UI

Swagger UI 是一个交互式界面，可以用来测试和查看 API。你可以在你的 Web 服务器中集成 Swagger UI。

4.1 在 main.go 中集成 Swagger UI

import (
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
)

func main() {
    r := gin.Default()

    // Swagger UI 路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // 启动服务器
    r.Run(":8080")
}

4.2 访问 Swagger UI

启动你的 Go 项目后，打开浏览器访问 //localhost:8080/swagger/index.html。你将看到自动生成的 API 文档，并可以在页面中直接测试 API。

5. 更新 Swagger 文档

每次你对 API 代码进行修改或添加新注释后，都需要重新运行 swag init 来更新 Swagger 文档。