管理员后台
API 可视化
面向管理员的 API 发现方案，基于 OpenAPI 聚合与 Scalar UI。
MuseMVP 通过三个仅管理员可访问的端点，提供完整的 API 文档链路。路由使用 hono-openapi 的 describeRoute 和 validator 自动生成 schema，配合 Scalar 渲染可交互的 API 参考界面。
适用场景
适合团队内部 API 文档共享、前后端对接、以及外部集成方查阅接口规范。
端点矩阵
GET /api/app-openapi
仅从 Hono 路由生成 OpenAPI schema，不含 Better Auth 路由。
GET /api/openapi
将应用 schema 与 Better Auth schema 合并为统一规范。
GET /api/docs
渲染可交互的 Scalar API 参考界面，支持搜索与试调用。
| 端点 | 用途 | 权限 |
|---|---|---|
GET /api/app-openapi | Hono 路由的 OpenAPI schema | 🔒 Admin |
GET /api/openapi | 合并后的 app + Better Auth 规范 | 🔒 Admin |
GET /api/docs | Scalar API 参考 UI | 🔒 Admin |
Swagger 生态兼容
内置 UI 使用 Scalar，但底层输出为标准 OpenAPI JSON，可与 Swagger 生态兼容：
| 使用场景 | 说明 |
|---|---|
| Swagger UI / Editor | 导入规范进行浏览与调试 |
| Postman / API 网关 | 从共享规范自动生成集合 |
| SDK / 类型生成 | 基于 OpenAPI 生成客户端代码 |
| CI 契约验证 | 在流水线中执行 API 兼容性检查 |
管理员使用指南
使用管理员账号登录。
访问 /api/docs，使用标签或搜索筛选端点。
访问 /api/openapi 导出原始规范，供 Swagger 兼容工具使用。
导入到工具链中，实现统一的 API 治理与协作。
生产环境建议
API 治理
建议将 /api/docs 和 /api/openapi 限制为仅管理员或内网可访问，防止接口细节泄露。
| 建议 | 说明 |
|---|---|
| 完善路由元数据 | 为每个路由在 describeRoute 中填写 summary、tags、responses |
| 视为契约 | 在 Code Review 中审查 OpenAPI 规范变更 |
| 限制访问范围 | 将 /api/docs 和 /api/openapi 保留给管理员或内网环境 |