接口文档生成

当前项目提供给 Apifox 导入的接口文件是：

docs/openapi.json

Apifox 可以直接导入 OpenAPI/Swagger 格式的 JSON 文件，所以当前阶段推荐使用 docs/openapi.json 作为接口文档源文件。

当前生成方式

当前项目接口数量还比较少，docs/openapi.json 是根据 Gin 路由和 Controller 手动整理出来的 OpenAPI 3.0 JSON。

也就是说，目前没有自动生成命令；维护方式是：

1. 修改或新增 Gin 接口。
2. 同步更新 docs/openapi.json。
3. 校验 JSON 格式。
4. 导入 Apifox。

校验 OpenAPI JSON

修改 docs/openapi.json 后，先执行：

jq empty docs/openapi.json

如果没有任何输出，表示 JSON 格式正确。

也可以查看当前文档里包含的接口路径：

jq '.paths | keys' docs/openapi.json

当前应包含：

[
  "/api/auth/external",
  "/api/auth/login",
  "/api/auth/register",
  "/api/conversations",
  "/api/conversations/detail",
  "/api/conversations/direct",
  "/api/conversations/groups",
  "/api/conversations/leave",
  "/api/conversations/members",
  "/api/conversations/members/role",
  "/api/conversations/messages",
  "/api/conversations/messages/list",
  "/api/conversations/messages/search",
  "/api/conversations/profile",
  "/api/conversations/read",
  "/api/devices",
  "/api/me",
  "/api/messages/read",
  "/api/messages/receipts",
  "/api/messages/search",
  "/api/messages/unread",
  "/api/resources/upload",
  "/api/users",
  "/api/users/presence",
  "/api/users/presence/batch",
  "/api/ws"
]

导入 Apifox

1. 打开 Apifox 项目。
2. 点击“导入数据”。
3. 选择 OpenAPI / Swagger。
4. 上传 docs/openapi.json。
5. 确认导入。

修改接口后的维护流程

新增接口时，建议按下面顺序同步：

# 1. 修改 Gin 路由、Controller、Model

# 2. 更新 OpenAPI JSON
vim docs/openapi.json

# 3. 校验 JSON 格式
jq empty docs/openapi.json

# 4. 确认接口路径
jq '.paths | keys' docs/openapi.json

# 5. 确认 Go 项目能编译
go build ./...

如果接口涉及 WebSocket 实时状态，还需要同步更新：

• docs/前端对接文档.md：事件信封、事件 payload、前端状态合并规则。
• docs/OVERVIEW.md：整体设计、典型流程和落地注意事项。
• README.md：常用入口和本地开发提示。

后续自动生成方案

如果接口越来越多，可以接入 swaggo/swag，通过代码注释自动生成 Swagger 文档。

安装命令：

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

常见生成命令：

swag init

如果入口文件不在默认位置，可以指定入口：

swag init -g main.go

生成后通常会得到：

docs/docs.go
docs/swagger.json
docs/swagger.yaml

其中 docs/swagger.json 可以导入 Apifox。

当前为什么没有直接使用 swag 自动生成

当前项目的接口注释还不是 swag 格式，例如还没有给 Controller 方法添加：

// @Summary 登录
// @Tags 认证
// @Accept json
// @Produce json
// @Param request body LoginRequest true "登录参数"
// @Success 200 {object} AuthResponse
// @Router /api/auth/login [post]

所以现在直接执行 swag init 不能得到完整接口文档。

如果后续要改成自动生成，需要先给每个接口补齐 swag 注释，再执行：

swag init -g main.go

然后把生成的 docs/swagger.json 导入 Apifox。

当前建议

当前阶段继续维护：

docs/openapi.json

当接口数量明显变多后，再切换到 swag init 自动生成。