自动生成接口文档的好处
说之前，先说一下自动生成接口文档有哪些好处？
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 注释中常用的字段类型及其详细解释：
- name：参数名
- in：参数位置
常见的参数位置包括 path、query、header、formData 和 body。
- path：路径参数，出现在 URL 路径中。例如，/users/{id} 中的 {id} 就是路径参数。
- query：查询参数，出现在 URL 的查询字符串中。例如，/users?name=John 中的 name 就是查询参数。
- header：请求头参数，出现在 HTTP 请求的头部信息中。
- formData：表单数据参数，出现在 POST 请求的表单数据中。
- body：请求体参数，出现在请求的消息体中，通常用于 POST 或 PUT 请求。
- type：参数类型
常见的数据类型包括 int、string、bool、float、time.Time 等。你也可以使用自定义的结构体类型作为参数类型。 - required：是否必填
true 表示必填，false 表示可选，默认为 false。 - description：参数描述
- format：参数格式
例如，当参数类型为 string 时，可以指定其格式为 email、date-time 等。 - enum：枚举值
表示参数的取值范围，用于限制参数的可选值。 - 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 钩子还具有一个优势，即如果文档生成过程失败（比如生成命令报错），它可以阻止提交的执行，确保只有在文档生成成功的情况下才会提交代码。
