Swagger / OpenAPI 文档

Zenith Admin 后端集成了 Swagger UI，开发时可直接在浏览器中浏览、调试所有 REST 接口，无需借助外部工具。

访问地址

路径	说明
`GET /api/docs`	Swagger UI 交互式界面
`GET /api/openapi.json`	OpenAPI 3.1 JSON Spec（可导入 Postman / Apifox）
`GET /metrics`	Prometheus 文本指标端点（非 OpenAPI 端点）

默认开发环境地址：

GET /api/docs、GET /api/openapi.json 与 GET /metrics 均无需认证，可直接访问。

以下端点由服务端直接暴露，但不属于 Swagger / OpenAPI 文档：

路径	说明
`GET /metrics`	Prometheus 文本格式指标，用于被 Prometheus Server 抓取

这类端点不返回 JSON schema，也不面向前端业务调试，因此不会出现在 /api/openapi.json 中。

所有需要登录的接口均使用 Bearer Token 认证。在 Swagger UI 中调试前需先完成授权：

OpenAPI Spec 自动生成，由 @hono/zod-openapi 在运行时从每个路由文件的 createRoute(...) 声明中汇总。无需维护任何静态文件。

在路由文件中用 createRoute(...) 声明新接口（设好 method、path、tags、request、responses）
确保路由已通过 app.route(prefix, router) 注册到 packages/server/src/index.ts
刷新 Swagger UI 即可看到新接口（无需改其他文件）

Spec 生成：packages/server/src/index.ts 中的 app.doc31('/api/openapi.json', { openapi: '3.1.0', ... })（doc31() 才能生成真正的 OpenAPI 3.1 格式 schema）
路由定义：packages/server/src/routes/*.ts 中每个路由使用 defineOpenAPIRoute({ route: createRoute({...}), handler }) 定义为命名常量，再通过 xxxRouter.openapiRoutes([...] as const) 统一注册（参考 packages/server/src/routes/api-tokens.ts）
公共 Schema 辅助：packages/server/src/lib/openapi-schemas.ts（响应辅助函数 ok(DTO, desc) / okPaginated(DTO, desc) / okMsg(desc)；公共 schema IdParam / PaginationQuery / BatchIdsBody；底层工具 jsonContent / validationHook / commonErrorResponses / ErrorResponse）
实体 DTO 中心仓库：按业务域拆分至 packages/server/src/lib/dtos/（iam / auth / dict / files / logs / notices / system / workflow / dashboard / region / messages），packages/server/src/lib/openapi-dtos.ts 为 re-export barrel —— 所有路由统一从 '../lib/openapi-dtos' 导入，保证 Swagger Components 单一来源，禁止在路由文件内本地重复声明 .openapi('EntityName') 的实体 DTO
认证方案：BearerAuth 在 packages/server/src/index.ts 中一次性注册到 app.openAPIRegistry
健康检查：packages/server/src/routes/health.ts 提供 GET /api/health，无需认证，可用于容器编排平台健康探针

以下仅列出核心分组，完整 Tag 列表请以 /api/doc Swagger UI 为准。