API 文档
网站在 /docs/api 提供只读接口参考。通过页面顶部选择 Web(含后台管理)或 Python,查看方法、路径、认证要求、参数、响应和示例。
| 分组 | 状态 | 定义来源 |
|---|---|---|
| Web | 已实现 | web.openapi.yaml |
| Python 服务 | 已实现 | python.openapi.json,由 FastAPI 导出 |
书写规则
- 使用 OpenAPI 3.1。每个操作填写唯一的 camelCase
operationId、简短summary、已登记的tags和security。公开接口写security: []。 - 有参数时写明位置、是否必填、类型及约束。JSON 和表单内容提供结构和示例。二进制内容注明媒体类型。
- 响应列出实际使用的状态码。示例中的 ID、Cookie、令牌和授权码使用占位值。
- 已实现的后台权限契约统一维护在 Web 规范。旧后台草案入口跳转到 Web 参考。网页展示文档,各接口的访问权限由服务端校验。
验证和更新
在仓库根目录运行 pnpm api:lint 校验两份规范。生产构建也会执行这个检查。
Python 路由、模型或示例有变动时,先运行 pnpm api:python:generate 更新快照,再运行 pnpm api:python:check 确认快照与源码一致。网页读取快照,Python 服务无需为展示文档而启动。