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 服务无需为展示文档而启动。