Gin 集成 swag 实现自动生成接口文档

前言

一个对新手很友好的 Go 项目(带界面)，开箱即用，WEB 界面一键安装，没有项目经验，完全可以拿这个练手，目前已经 5.1K Star。

• GitHub: github.com/xinliangnot...
• 中文文档：www.yuque.com/xinliangnot...

说之前，先说一下自动生成接口文档有哪些好处？

1）节省时间和工作量：手动编写接口文档是一项耗时且繁琐的任务。通过自动生成接口文档，可以大大减少编写文档的时间和工作量，提高开发效率。

2）保持文档与代码同步：代码和文档往往是不同步的，当代码发生变更时，手动更新文档可能容易出现遗漏或错误。自动生成接口文档可以保持文档与代码的同步，确保文档的准确性和实时性。

3）提供一致的文档格式：通过自动生成接口文档，可以定义一致的文档格式和结构，使得所有接口文档都具有相同的风格和组织方式。这样可以提高文档的可读性和易用性，减少理解和使用文档的成本。

4）方便团队协作和交流：自动生成的接口文档可以作为团队协作和交流的重要工具。团队成员可以很方便地查阅接口文档，了解接口的定义、参数、返回值等信息，从而更好地进行开发、测试和集成工作。

5）提升接口的可测试性：自动生成的接口文档通常会包含接口的请求示例和响应示例，这些示例可以用于接口的测试和验证。这样可以提升接口的可测试性，减少开发人员在编写测试代码时的工作量。

总的来说，自动生成接口文档可以大大提高开发效率、保持文档与代码同步、提供一致的文档格式、方便团队协作和交流，并提升接口的可测试性。这对于项目的开发和维护都是非常有益的。

接下来，说一下咱们项目使用的工具包：Swag。

目前在项目中已经集成完毕，大家只要写好注释即可，就可以生成接口文档。接口文档地址：http://127.0.0.1:9999/swagger/index.html

为了安全起见，接口文档地址在 -env=pro 时，不可预览！

在 Go 语言中，Swagger 是一种用于描述和定义 RESTful API 的规范。Go Swag 是一个用于自动生成 Swagger 文档的工具。为了使用 Go Swag 生成 Swagger 文档，你需要在代码中添加相应的注释。

以下是一些常见的 Go Swag 注释示例：

// @Summary 创建管理员
// @Description 创建管理员
// @Tags API.admin
// @Accept application/x-www-form-urlencoded
// @Produce json
// @Param username formData string true "用户名"
// @Param mobile formData string true "手机号"
// @Success 200 {object} createResponse
// @Failure 400 {object} code.Failure
// @Router /api/admin [post]

其中：

• @Summary 表示 API 接口的简要说明。
• @Description 表示 API 接口的详细描述。
• @Tags 表示 API 接口所属的标签。
• @Accept 表示 API 接口所支持的请求格式。
• @Produce 表示 API 接口所支持的响应格式。
• @Param 表示 API 接口的参数，包括参数名、类型、是否必填等信息。
• @Success 表示 API 接口的成功响应结果，包括状态码和返回数据类型。
• @Failure 表示 API 接口的失败响应结果，包括状态码和错误信息类型。
• @Router 表示 API 接口的路由地址。

@Tags

用于对 API 接口进行标记和分类。它可以帮助组织和管理 API 接口，并在生成的 Swagger 文档中展示接口的标签信息。

@Tags 注释参数用于指定 API 接口所属的标签或分类。该参数可以设置一个或多个值，每个值表示一个标签，使用半角逗号,分隔。标签可以根据业务功能、模块或者其他自定义规则进行分类。例如，你可以使用以下标签：Users、Orders、Products 等。

通过在 API 接口注释中使用 @Tags 参数，可以将接口按照功能或模块进行分类。这些标签将在生成的 Swagger 文档中呈现出来，方便用户浏览和查找相关的接口。同时，Swagger UI 也可以通过标签进行接口的过滤和展示。

@Accept

用于指定 API 接口所支持的请求内容类型。它可以帮助生成准确的 Swagger 文档，并向用户展示 API 接口接受的请求数据类型。

@Accept 注释参数用于指定 API 接口接受的请求内容类型。该参数可以设置多个值，每个值表示一个请求内容类型，使用半角逗号,分隔。

常见的请求内容类型包括：

• application/json：JSON 格式数据
• application/xml：XML 格式数据
• application/octet-stream：二进制数据
• multipart/form-data：表单数据
• text/plain：纯文本数据
• application/x-www-form-urlencoded：URL 编码的数据

在实际使用中，你可以根据 API 接口的需求，设置不同的请求内容类型。这些注释参数将会在生成的 Swagger 文档中显示出来，方便用户了解和使用 API 接口。

@Produce

用于指定 API 接口返回的响应内容类型。它可以帮助生成准确的 Swagger 文档，并向用户展示 API 接口可能返回的不同数据格式。

@Produce 注释参数用于指定 API 接口返回的响应内容类型。该参数可以设置多个值，每个值表示一个响应内容类型，使用半角逗号,分隔。

常见的响应内容类型包括：

• application/json：JSON 格式数据
• application/xml：XML 格式数据
• text/plain：纯文本数据
• image/jpeg：JPEG 图像数据
• application/pdf：PDF 文档数据

在实际使用中，你可以根据 API 接口的需求，设置不同的响应内容类型。这些注释参数将会在生成的 Swagger 文档中显示出来，方便用户了解和使用 API 接口。同时，Swagger UI 也会根据这些参数提供相应的选择和展示。

@Param

用于标识 API 接口的参数。它包含多个字段，每个字段都表示参数的不同属性。

以下是 @Param 注释中常用的字段类型及其详细解释：

1. name：参数名

2. in：参数位置

   常见的参数位置包括 path、query、header、formData 和 body。

   • path：路径参数，出现在 URL 路径中。例如，/users/{id} 中的 {id} 就是路径参数。
   • query：查询参数，出现在 URL 的查询字符串中。例如，/users?name=John 中的 name 就是查询参数。
   • header：请求头参数，出现在 HTTP 请求的头部信息中。
   • formData：表单数据参数，出现在 POST 请求的表单数据中。
   • body：请求体参数，出现在请求的消息体中，通常用于 POST 或 PUT 请求。

3. type：参数类型

   常见的数据类型包括 int、string、bool、float、time.Time 等。你也可以使用自定义的结构体类型作为参数类型。

4. required：是否必填

   true 表示必填，false 表示可选，默认为 false。

5. description：参数描述

6. format：参数格式

   例如，当参数类型为 string 时，可以指定其格式为 email、date-time 等。

7. enum：枚举值

   表示参数的取值范围，用于限制参数的可选值。

8. default：默认值

在实际使用中，你可以根据具体的 API 接口需求，设置不同的参数类型、位置和属性。这些参数注释将帮助生成准确的 Swagger 文档，并提供给用户参考和使用。

@Router

用于指定 API 接口的路由信息，包括 HTTP 方法和路径。

需要注意的是，在使用 @Router 参数时，需要将 HTTP 方法和路径放在方括号内，中间使用空格分隔。同时，路径中的路径参数也需要使用大括号进行标记。

在 Swag 中，使用 @Router 参数来描述 API 接口的路由信息，可以让 Swagger 自动生成 API 文档，并且方便测试人员和开发人员快速了解和测试 API 接口。

@Security

用于指定 API 接口的安全需求和认证要求。通过使用 @Security 参数，可以指定 API 接口需要的安全方案，以及安全方案的作用范围。

在实际使用中，@Security 参数通常与安全方案定义结合使用。安全方案可以包括 API 密钥认证、基本认证、OAuth 等各种认证方式。

通过使用 @Security 参数，可以让 Swagger 自动生成的 API 文档中明确显示出每个 API 接口所需要的安全认证信息，以及开发人员如何进行相应的认证操作。总之，@Security 参数在 Swag 中用于指定 API 接口的安全需求和认证要求，帮助开发人员和测试人员快速了解 API 接口的安全要求，以及进行相应的测试和调试。

入口注释

入口注释通常位于 Go 代码文件的第一行或者紧跟在包声明语句后面。它使用特定的格式和指令来描述 API 的基本信息、API 版本、作者、许可证等内容。这些元数据信息会被 Swag 解析并生成对应的 API 文档。

以下是一个典型的入口注释的示例：

// Package main provides ...
//
// @title My Awesome API
// @description This is a sample API for demonstration purposes.
// @version 1.0
// @termsOfService https://example.com/terms
// @contact.email admin@example.com
// @license.name MIT
// @host localhost:8080
// @BasePath /api/v1

在上述示例中，入口注释是以 // 开头的注释块。它包含了各种指令，以 @ 符号开头，用于描述 API 的各种属性。

常见的入口注释指令包括：

• @title：定义 API 的标题或名称。
• @description：描述 API 的简要说明。
• @version：指定 API 的版本号。
• @termsOfService：指定服务条款的 URL。
• @contact.email：指定联系人的电子邮件地址。
• @license.name：指定 API 的许可证名称。
• @host：指定 API 的主机名和端口号。
• @BasePath：指定 API 的基本路径。

通过在入口注释中使用这些指令，可以为整个 API 定义基本信息，并设置全局配置。Swag 将解析这些注释并生成对应的 API 文档，包括标题、描述、版本号、联系人信息等。

入口注释是 Swag 中非常重要的一部分，它提供了定义整个 API 的基本元数据的方式，使得生成的 API 文档更加规范和易读。同时，这些元数据也对开发人员和测试人员提供了有用的信息，帮助他们了解和使用 API。

生成文档

go install github.com/swaggo/swag/cmd/swag
swag init

文档生成完毕后，需要重新启动项目才会生效。

脚本化

Mac / Linux

swagger.sh

#!/bin/bash
printf "\nRegenerating swagger doc\n\n"
go install github.com/swaggo/swag/cmd/swag@v1.16.2
time swag init
printf "\nDone.\n\n"

Windows

swagger.bat

@echo off
chcp 65001
echo.
echo Regenerating swagger doc
echo.
go install github.com/swaggo/swag/cmd/swag@v1.16.2
swag init
echo.
echo Done.

执行脚本

// Mac / Linux 环境，在项目根目录下运行 
./scripts/swagger.sh

// Windows 环境，在项目根目录下运行
./scripts/swagger.bat

Git commit 钩子

Git commit 钩子是一种在执行 git commit 命令时触发的自定义脚本或程序，可以让开发人员在提交代码之前或之后执行特定的操作。

Git 提供了预定义的一些钩子点，其中包括 pre-commit 和 post-commit 钩子，它们分别在执行提交前和提交后触发。

pre-commit 钩子：在执行 git commit 前触发，可以用于在提交前进行代码风格检查、静态代码分析、单元测试等操作。如果 pre-commit 钩子中的操作失败（比如代码风格不符合规范、单元测试未通过），则会阻止提交的执行。

post-commit 钩子：在执行 git commit 后触发，可以用于执行一些与提交相关的操作，比如发送通知、记录提交信息到日志、触发持续集成/部署流程等。

通过使用这些钩子，开发团队可以实现一些自动化的流程，例如确保提交的代码符合规范、自动生成文档、触发自动化测试、以及在提交完成后通知团队成员等。这有助于提高代码质量、减少人为错误，并促进团队协作。

要使用这些钩子，只需在项目的 .git/hooks 目录下创建相应的脚本文件（如 pre-commit 或 post-commit），并赋予执行权限即可。这些脚本可以是任意可执行文件，比如 shell 脚本、Python 脚本等。当执行 git commit 时，Git 会自动触发相应的钩子脚本。

我们可以将「生成文档的脚本」放到 pre-commit 钩子中，通过在 pre-commit 钩子中执行文档生成命令或脚本，可以在每次提交代码之前自动更新文档，使得文档与代码保持同步。

另外，pre-commit 钩子还具有一个优势，即如果文档生成过程失败（比如生成命令报错），它可以阻止提交的执行，确保只有在文档生成成功的情况下才会提交代码。

项目代码

• GitHub: github.com/xinliangnot...
• 中文文档：www.yuque.com/xinliangnot...