Qdrant 新增 REST 端点后如何更新 OpenAPI 规范从 ytt 文件到 redoc 验证的完整流程【免费下载链接】qdrantQdrant - High-performance, massive-scale Vector Database and Vector Search Engine for the next generation of AI. Also available in the cloud https://cloud.qdrant.io/项目地址: https://gitcode.com/GitHub_Trending/qd/qdrant在 Qdrant 的 Rust 代码里新增或修改了一个 REST 端点后光改代码是不够的Qdrant 用 OpenAPI 规范描述 API规范要求“API 变更必须同步到规范文件且由 CI 强制检查”见 docs/DEVELOPMENT.md 的API changes → REST一节。如果不同步test-consistencyCI 任务会跑 tests/openapi_consistency_check.sh 重新生成规范并与仓库中已提交的文件做 diff有差异就直接失败。这篇文章走一遍完整路径从在openapi/*.ytt.yaml里写端点定义、在src/schema_generator.rs里登记模型到运行tools/generate_openapi_models.sh生成规范、用 redoc 页面人工验证最后跑集成测试确认行为。适用前提你在本地 clone 了 qdrant 仓库机器上有 Rust 工具链cargo、jq和 Docker生成脚本会构建并运行两个镜像ytt/yq未安装时脚本自动回退到 Docker 版本。规范文件由哪些部分组成先看清楚生成脚本 tools/generate_openapi_models.sh 的数据流后面每步修改的文件就都对应上了端点定义openapi/*.ytt.yaml如 openapi/openapi-service.ytt.yaml使用 openapi/openapi.lib.yml 提供的 ytt 辅助函数response、reference、type、array等描述路径、参数和响应模型定义src/schema_generator.rs中的AllDefinitions结构体通过schemars把 Rust 类型转成 JSON Schema输出openapi/schemas/AllDefinitions.json再由tools/schema2openapi容器转成openapi/models.yaml合并脚本把 9 个openapi-*.yaml和models.yaml合并为openapi/openapi-merged.yaml/openapi-merged.json并拷贝到 docs/redoc/master/openapi.json——这就是 redoc 页面加载的文件也是 CI 一致性检查比对的目标。第一步实现 Rust 端点与模型按照 DEVELOPMENT.md 的第 1 步先在 Rust 代码里完成端点和模型lib/api下的 REST 模型、src/actix/api下的路由。模型类型会被AllDefinitions引用所以最终要能进 OpenAPI 组件表。第二步修改openapi/*.ytt.yaml添加端点端点按功能归属到对应的 ytt 文件openapi-main、openapi-collections、openapi-points、openapi-service、openapi-cluster、openapi-quotas、openapi-snapshots、openapi-shards、openapi-shard-snapshots生成脚本对每个文件逐一执行ytt。文件开头统一加载公共库# load(openapi.lib.yml, response, reference, type, array)下面是 openapi/openapi-service.ytt.yaml 中现有GET /端点的原文示例可以照这个结构新增路径、operationId、tags和响应paths: /: get: summary: Returns information about the running Qdrant instance description: Returns information about the running Qdrant instance like version and commit id operationId: root tags: - Service responses: 200: description: Qdrant server version information content: application/json: schema: $ref: #/components/schemas/VersionInfo 4XX: description: error第三步在src/schema_generator.rs登记新模型src/schema_generator.rs 里有一个#[derive(Serialize, JsonSchema)]的AllDefinitions结构体每个字段对应一个要导出到components/schemas的 Rust 类型#[derive(Serialize, JsonSchema)] struct AllDefinitions { a1: CollectionsResponse, a2: CollectionInfo, // ... 现有字段 ... br: segment::data_types::vector_name_config::VectorNameConfig, bs: QuotaStatus, }如果你的新端点引入了新的请求/响应模型就在该结构体里加一个字段字段名如a*/b*只是编号习惯类型必须实现schemars::JsonSchema。已有模型如VersionInfo、Usage已登记无需重复添加。第四步运行生成脚本在仓库根目录执行./tools/generate_openapi_models.sh脚本内部依次做这些动作脚本有set -e任一步失败会立即退出检查本地ytt没有则用gerritk/ytt镜像执行对 9 个openapi-*.ytt.yaml逐个生成openapi/*.yamlcargo run --package qdrant --featuresservice_debug --bin schema_generator生成openapi/schemas/AllDefinitions.jsondocker build tools/schema2openapi并用容器把 JSON Schema 转成openapi/models.json再用yq转成models.yaml本地无yq时回退到mikefarah/yq镜像合并所有文件为openapi/openapi-merged.yaml然后用redocly/openapi-cli:v1.0.0-beta.88容器执行lint openapi-merged.yaml——lint 不过脚本会失败这是第一道机器校验转成 JSON 并cp到docs/redoc/master/openapi.json。副作用说明该脚本会构建本地 Docker 镜像schema2openapi、拉取/运行上述容器并覆盖写入openapi/目录下全部生成文件和docs/redoc/master/openapi.json——这些文件本身就是需要随代码一起提交的产物属于预期行为。前置依赖Docker、cargo、jq脚本最后一步用jq格式化没有本地回退CI 里是用apt-get install -y clang jq装的本地需自行保证jq可用。第五步redoc 页面验证按 DEVELOPMENT.md 的 6、7 步在docs/redoc目录下起一个静态文件服务python -m http.server然后浏览器打开http://localhost:8000/?vmaster。?vmaster参数不能省docs/redoc/default_version.js 里默认版本是v1.18.x不带参数加载的是历史版本快照只有?vmaster才加载刚生成的 docs/redoc/master/openapi.json。检查点新增端点出现在对应 tag 分组下、请求参数和响应模型渲染正确。DEVELOPMENT.md 的第 8 步建议再把openapi-merged.yaml贴进 Swagger Editor 做一次可视化校验确认无告警。第六步更新并运行集成测试DEVELOPMENT.md 第 5 步要求在 tests/openapi 下更新或新增对应测试然后运行uv --project tests run pytest tests/openapi前置条件本地有一个可访问的 Qdrant 实例在localhost:6333测试通过 HTTP 直接打本地服务参考 tests/integration-tests.shCI 的做法是先启动./target/debug/qdrant再跑 pytest。uv未安装时先按 DEVELOPMENT.md 的本地开发一节安装。别忘了metrics 白名单与端点总数DEVELOPMENT.md 的System integration一节指出新增端点还要把新端点加进src/common/metrics.rs的 metrics 白名单JWT 相关改动需要过tests/auth_tests。这一点和一致性检查脚本直接挂钩tests/openapi_consistency_check.sh 除了比对生成结果与仓库文件通过则输出 No diffs found.还会统计openapi.json中路径总数并与脚本内的EXPECTED_NUMBER_OF_APIS当前仓库中为69比较。数量不符时脚本给出的处理建议是确认新端点在 metrics 端点的白名单REST_ENDPOINT_WHITELIST/GRPC_ENDPOINT_WHITELIST中配置正确一致性恢复后更新脚本里的EXPECTED_NUMBER_OF_APIS。CI 侧的验收本地全部通过后integration-tests工作流的test-consistency任务会以同样的方式复核构建schema2openapi镜像、装好clang/jq与 protoc 后执行./tests/openapi_consistency_check.sh。它先把docs/redoc/master/openapi.json复制为.diff.openapi.json重新运行tools/generate_openapi_models.sh再diff两者——所以生成文件必须提交而不是只在本地跑一遍。限制说明生成脚本强依赖 Dockerschema2openapi镜像构建和 redocly lint 都在容器里执行无 Docker 环境无法完成第 4 步。EXPECTED_NUMBER_OF_APIS 69是当前脚本中的固定值每新增端点都要同步更新否则即使 diff 一致也会因数量检查失败。本文只覆盖 REST 规范链路gRPC 侧lib/api/src/grpc/proto/*.proto与tests/basic_grpc_test.sh是 DEVELOPMENT.md 中另一条独立流程不在本任务范围内。【免费下载链接】qdrantQdrant - High-performance, massive-scale Vector Database and Vector Search Engine for the next generation of AI. Also available in the cloud https://cloud.qdrant.io/项目地址: https://gitcode.com/GitHub_Trending/qd/qdrant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考