refactor(web): API 路由统一 /api 前缀 + 完善 OpenAPI 文档

- 路由挂 APIRouter(prefix="/api"),健康检查路径 /health -> /api/health,
  后期加接口(/api/compare、/api/queue 等)自动共享前缀。
- 文档路径归到 /api 下:/api/docs、/api/redoc、/api/openapi.json
  (原 /docs、/redoc、/openapi.json 已 404)。
- 新增 Pydantic 响应模型 schemas.py,并在 /api/health 挂 response_model,
  使 /api/docs 展示完整响应结构。
- 为接口和每个响应字段补详细英文 description(覆盖范围、status 三态判定、
  HTTP 码含义、各字段语义如 cycle_lag 阈值/dead 含义等)。

不动业务逻辑与同步主循环,仅 Web 层。
This commit is contained in:
Misaka_Company
2026-08-05 12:55:45 +08:00
parent 03d7bcea39
commit 79a95465e7
4 changed files with 277 additions and 20 deletions

View File

@@ -22,6 +22,11 @@ def create_app(state: ServiceState, cfg: SyncConfig) -> FastAPI:
title="DataMacroSync",
description="Access -> SQL Server incremental sync operational API",
version="1.0.0",
# Keep all auto-generated docs under /api alongside the operational
# routes, so the whole HTTP surface shares one prefix.
docs_url="/api/docs",
redoc_url="/api/redoc",
openapi_url="/api/openapi.json",
)
deps.bind(state, cfg)
app.include_router(health_routes.router)