X-Financial/document/development/backend_api/README.md

Backend API Swagger 文档

本目录用于沉淀后端接口的 Swagger / OpenAPI 产物，给开发、联调和后续 Agent 接口调用统一对照。

目录说明

• openapi.json
  • 由 FastAPI app.openapi() 导出的完整 OpenAPI 规范。
• interface_inventory.md
  • 基于 OpenAPI 自动整理的接口清单，按 tag 分组查看方法、路径和摘要。

在线入口

• Swagger UI：/docs
• ReDoc：/redoc
• OpenAPI JSON：/openapi.json

如果本地默认端口不变，完整地址通常是：

• http://127.0.0.1:8000/docs
• http://127.0.0.1:8000/redoc
• http://127.0.0.1:8000/openapi.json

重新生成

在 /app/server 下执行：

PYTHONPATH=/app/server/src /app/server/.venv/bin/python /app/server/scripts/export_openapi.py

当前约定

• 全部业务接口前缀：/api/v1
• 知识库接口使用请求头模拟登录用户：
  • X-Auth-Username
  • X-Auth-Name
  • X-Auth-Role-Codes
  • X-Auth-Is-Admin
• Agent 资产写接口支持审计头：
  • X-Actor
  • X-Request-Id
• Hermes 运行时模型接口使用：
  • Authorization: Bearer <HERMES_AGENT_SHARED_TOKEN>