Skip to content

[1.25.x] refactor(dashboard): migrate automatic API docs to OpenAPI 3.1 - #3246

Draft
wklken wants to merge 1 commit into
TencentBlueKing:masterfrom
wklken:feat/dashboard-oas3-docs
Draft

[1.25.x] refactor(dashboard): migrate automatic API docs to OpenAPI 3.1#3246
wklken wants to merge 1 commit into
TencentBlueKing:masterfrom
wklken:feat/dashboard-oas3-docs

Conversation

@wklken

@wklken wklken commented Sep 6, 2026

Copy link
Copy Markdown
Collaborator

Description

Dashboard 自动接口文档目前由 drf-yasg 生成 Swagger 2.0。本 PR 从 upstream/master(fcba90a5b)独立切分,改用 drf-spectacular 生成 OpenAPI 3.1 JSON/YAML,保留现有 DEBUG-only 文档地址。Swagger UI 和 ReDoc 使用 sidecar 本地静态资源。

将现有 schema 标注迁移到原生 extend_schema / extend_schema_field,保留参数、说明和组件命名,并描述 Web/V2、V1、分页、文件上传下载及直接 JSON 响应的实际结构。保留筛选参数、DELETE JSON 请求体,以及现有 PATCH 处理器实际要求的必填字段;支持部分更新的处理器仍生成可选字段。业务接口处理逻辑和资源导入导出路径保持原有行为。资源旧 Swagger 2.0 导出清理由 #2989 单独处理。

验证:

  • Dashboard uv run make lint-check 通过。
  • Dashboard uv run make test:3964 passed。
  • 完整 OAS3 schema 生成及校验通过,0 errors。仍有 333 次生成警告(320 unique),主要是现有序列化字段缺少类型提示、queryset 推断与枚举命名;不代表所有字段都已有精确类型。
  • 迁移前后均为 302 条路径;操作数从 377 到 376,仅隐藏 metrics query-summary export 从 CreateAPIView 继承但无法工作的 POST,实际 GET 导出保留。
  • JSON/YAML、DEBUG 开关、分页/响应包装、multipart、二进制下载及本地 UI 资源均有验证;uv lock --check 通过。
  • 已完成旧符号和依赖引用扫描。尚未在联调部署环境验证;GitHub CI 以远端结果为准。

Checklist

  • 填写 PR 描述及相关 issue (write PR description and related issue)
  • 代码风格检查通过 (code style check passed)
  • PR 中包含单元测试 (include unit test)
  • 单元测试通过 (unit test passed)
  • 本地开发联调环境验证通过 (local development environment verification passed)

@wklken
wklken marked this pull request as draft September 7, 2026 02:52
@wklken

wklken commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator Author

for 1.25.x
and we should fetch newest upstream/master and update the new added apis too

@wklken wklken changed the title refactor(dashboard): migrate automatic API docs to OpenAPI 3.1 [1.25.x] refactor(dashboard): migrate automatic API docs to OpenAPI 3.1 Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant