使用 Go 自动生成 Swagger API 文档教程

Swagger 文档基本介绍

Swagger 2.0 和 OpenAPI 3.0 都是用于描述 RESTful API 的规范。它们的主要目的是使不同的开发者和团队能够轻松地了解和使用 API，同时提高 API 的可维护性和互操作性。

Swagger 2.0 是早期版本的规范，它定义了一组基于 JSON 或 YAML 的规则，以描述 API 的各种方面，如端点、操作、参数、响应等。Swagger 2.0 可以通过 Swagger UI 在浏览器中直接查看 API 的文档和测试 API。它已成为一个流行的 API 规范，并被许多公司和开发者广泛采用。

OpenAPI 3.0 是 Swagger 2.0 的后续版本。它是一种更加灵活和强大的 API 规范，具有更丰富的功能和更好的可扩展性。OpenAPI 3.0 采用了 YAML 语法，并增加了许多新的功能，如结构化的响应定义、请求体定义、更好的错误处理等。与 Swagger 2.0 不同，OpenAPI 3.0 可以定义 SOAP 和 RPC API，而不仅仅是 RESTful API。OpenAPI 3.0 也提供了一个基于 JSON 的默认格式，可以使用许多不同的工具生成 API 文档和客户端代码。

Go 生态中 Swagger 开源项目介绍

go-swagger

go-swagger 是一个用于构建、文档化和测试 Go RESTful API 的工具。它支持 Swagger 2.0 和 OpenAPI 3.0 规范，并提供了生成客户端和服务器端代码的功能。使用 go-swagger 可以简化 API 的开发和维护，并提高 API 的可读性和可测试性。

swag

swag 是一个用于自动生成 Swagger 文档的 Go 注释工具。它可以解析 Go 源代码中的 Swagger 注释，并将它们转换为 Swagger 文档。使用swag可以快速生成Swagger文档，提高API的可读性和可测试性。

kin-openapi

kin-openapi 是一个用于验证和解析 OpenAPI 3.0 规范的 Go 库。它提供了一组工具，可以轻松地加载、验证和操作 OpenAPI 文档。使用 kin-openapi 可以确保你的 API 符合 OpenAPI 规范，并提高 API 的可靠性和可测试性。

oapi-codegen

oapi-codegen 是一个用于生成 Go 客户端和服务器端代码的 OpenAPI 3.0 代码生成器。它基于 OpenAPI 规范，可以将 OpenAPI 文档转换为可用的 Go 代码。使用 oapi-codegen 可以加速 API 的开发过程，同时提高代码的可靠性和可测试性。

你需要 OpenAPI V3 还是 Swagger 2.0 ? 截止到目前， 我还没有找到一个合适的工具能直接在 Go 项目中生成 OpenAPI 3.0 文档。所以接下来会介绍快速生成 Swagger 2.0 的步骤。

快速生成 Swagger 2.0 的步骤

接入流程

接入流程主要分为以下几个步骤：

1. main 文件中添加注释-配置 Server，服务信息
2. controller 中添加注释-配置接口，接口信息
3. swag init 生成 docs 目录
4. 配置 handler 访问

示例项目

大家可以参考这个项目

安装swag

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

支持解析并输出 docs/docs.go

配置服务信息

main.go 中引入以下两个包：

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

安装必要拓展

 go get -u -v github.com/swaggo/gin-swagger
 go get -u -v github.com/swaggo/files
 go get -u -v github.com/alecthomas/template

添加 server 描述

// 添加注释以描述 server 信息
// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/
// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io
// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
// @host      localhost:8080
// @BasePath  /api/v1
// @securityDefinitions.basic  BasicAuth
func main() { 
   r := gin.Default()    c := controller.NewController()    v1 := r.Group("/api/v1")    {        accounts := v1.Group("/accounts")        {            accounts.GET(":id", c.ShowAccount)        }    //...
}
r.Run(":8080")}//...

最新的定义可以查看官网文档， 以下仅仅是罗列官网的

配置 Controller

// ShowAccount godoc
// @Summary      Show an account
// @Description  get string by ID
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "Account ID"
// @Success      200  {object}  model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts/{id} [get]
func (c *Controller) ShowAccount(ctx *gin.Context) {  id := ctx.Param("id")  aid, err := strconv.Atoi(id)  if err != nil {    httputil.NewError(ctx, http.StatusBadRequest, err)    return  }  account, err := model.AccountOne(aid)  if err != nil {    httputil.NewError(ctx, http.StatusNotFound, err)    return  }  ctx.JSON(http.StatusOK, account)}

运行命令生成 docs

如果你写的注释格式没问题，此时你的项目根目录下会多出一个 docs 文件夹。

swag init

配置文档 handler

最后则是在 router 中增加 swagger 的 handler 了。

在 main.go 或其他地方增加一个 handler.

engine := gin.New()engine.GET("swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

访问测试

项目运行起来后访问ip:port/swagger/index.html 即可看到 API 文档。

更多流程参考

直接采用 Apifox

过去因为前端小伙伴强烈推荐 Swagger 文件， 我给 Go 项目集成了 Swagger，结果发现泛型等复杂类型的支持并不是很友好，导致我在项目代码中维护了一份 yaml 文件，尽管看起来能勉强交付给起前端团队，不过因为没有类型安全，导致事故频发。 对于 Go 项目，可以采取 Codegen 方式，但我更推荐使用 Apifox 在线设计。

Apifox 支持在线设计并导出 swagger 文件， 生成服务端和客户端代码。 对于软件开发来说， 有了 Swagger 在线文档并不足够， 我们还有可能利用 Mock 和自动化测试 ，Apifox 作为 API 一体化协作平台，确实帮助软件开发团队实现快速迭代交付。

现在越来越多的小伙伴们使用 Apifox，Apifox 中以 JSON 的结构设计 API， 调试支持云端 Mock ，支持套件测试 ，居然还支持代码生成，大大提升了 API 开发效率和接口文档维护效率。

知识扩展：

• 深入了解 Swagger 生态：探索 Swagger 工具
• 了解 Swagger Hub：构建和管理API 文档的完美平台