# 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>`