45 lines
1.1 KiB
Markdown
45 lines
1.1 KiB
Markdown
# 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` 下执行：
|
||
|
||
```bash
|
||
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>`
|