跳到主要内容

Swagger / OpenAPI 文档

disaster-server 内置 Swagger / OpenAPI 文档能力。它不是从 Go handler 注释临时生成，而是读取固定的 OpenAPI 契约文件，并在 swagger.enabled=true 时暴露 Swagger UI、OpenAPI YAML 和 OpenAPI JSON。

这部分文档用于说明如何打开、访问、导出和维护项目接口契约。

启用条件​

Server 只有在配置中显式开启 Swagger 时才注册文档路由：

swagger:
  enabled: true

代码中的默认值是关闭：

swagger.enabled=false

生产环境建议保持关闭，或只在受控内网、发版验收环境、测试环境中开启。Swagger 路由不挂载业务 JWT 中间件，访问控制应由网络边界、Ingress 白名单、网关认证或环境隔离保证。

如果使用 Helm 部署，确认 disaster-server 的 ConfigMap 中包含上面的 swagger.enabled=true，然后重启 server Pod 让配置生效。

server 当前配置文件位置、本地与 Helm 配置来源、server.env/JWT/License 等字段说明见 Server 配置。

访问入口​

开启后，Server 注册以下入口：

路径说明
/swagger/Swagger UI 页面，浏览器直接打开。
/openapi.yamlOpenAPI YAML 契约文件。
/openapi.jsonOpenAPI JSON 契约文件，由 YAML 转换得到。

示例：

http://<server-host>:<server-port>/swagger/
http://<server-host>:<server-port>/openapi.yaml
http://<server-host>:<server-port>/openapi.json

Swagger UI 页面会同源加载 /openapi.yaml。

备注

当前 Swagger UI 页面使用 swagger-ui-dist@5 的 CDN 资源。如果部署环境不能访问外网，/openapi.yaml 和 /openapi.json 仍然可用；如需完全离线访问 Swagger UI，应将 Swagger UI 静态资源本地内置，或由网关统一托管。

契约源文件​

OpenAPI 源文件路径：

disaster-server/openspec/specs/disaster-server-openapi.yaml

约束：

  • OpenAPI 版本固定为 3.0.3。
  • Swagger UI、/openapi.yaml、/openapi.json 和发版校验都读取同一份契约。
  • 脚本生成的中间产物不能作为事实源。
  • 修改 server API 契约时，必须同步更新这个文件。

导出 OpenAPI​

在可访问 server 的环境中：

curl -o disaster-server-openapi.yaml http://<server>/openapi.yaml
curl -o disaster-server-openapi.json http://<server>/openapi.json

导出的文件可以导入 Postman、Apifox、Apipost、Swagger Editor 或其他 OpenAPI 工具。

本地校验​

在 disaster-server 仓库中校验 OpenAPI 文件：

go run ./tools/openapi validate \
  --spec openspec/specs/disaster-server-openapi.yaml

如果需要和 server 路由清单、RunAPI/Apipost 清单做对账，可使用同一工具中的 routes、diff、checklist 子命令。当前仓库已经保留了相关 artifacts，用于发版前检查接口是否漏写、错位或未补 schema。

文档站生成策略​

当前文档站仍保留手写 API 文档，用于解释认证、错误码、状态机、业务语义和典型示例。Swagger/OpenAPI 负责接口契约、请求响应字段和机器可读 schema。

可按两阶段接入自动生成参考页：

  1. 保留当前手写 API 文档，用于说明业务语义、状态机和示例。
  2. 增加生成脚本，把 OpenAPI JSON/YAML 转换为可浏览的 API Reference。

候选方案：

  • 使用 Docusaurus OpenAPI 插件生成页面。
  • 将 Swagger UI 作为独立页面嵌入。
  • 在 CI 中校验 OpenAPI 与 server 源文件一致。

发版验收标准​

  • swagger.enabled=true 的验收环境中，/swagger/ 可以打开。
  • /openapi.yaml 返回 OpenAPI YAML。
  • /openapi.json 返回 JSON，并且内容与 YAML 同源。
  • go run ./tools/openapi validate --spec openspec/specs/disaster-server-openapi.yaml 通过。
  • 新增或修改 API 时，OpenAPI、手写 API 文档、错误码说明和 RunAPI/Apipost 保持一致。
  • OpenAPI 示例不得包含真实 token、kubeconfig、AccessKey、SecretKey、License 或内网敏感地址。

维护规则​

修改 server API 时，应同步：

  • handler 行为。
  • DTO 和请求/响应字段。
  • OpenAPI spec。
  • 手写 API 说明。
  • 错误码和认证语义。

如果接口会驱动 operator 行为，还需要同步 operator CRD 字段、状态字段和控制器行为说明。Swagger 只说明 server 外部接口契约，不能替代容灾流程、状态机和运维 runbook 文档。