Windmill 仓库 OpenAPI 规范同步指南让 Rust 后端 API 与 openapi.yaml 始终一致【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill本文是一份面向 Windmill 开源仓库维护者与二次开发者的 API 文档工程指南。它围绕仓库中openapi-syncAgent 的工作方法论展开系统讲解如何在 Rust 后端windmill-apicrate增删改 API 端点、修改请求/响应结构体、或调整 Flow 数据结构时同步维护两份 OpenAPI 规范文件保证契约、客户端生成与文档的一致性。读完本文你将掌握 Windmill 的 OpenAPI 文件布局、从 Rust 实现到 OpenAPI Schema 的类型映射规则、规范化的同步工作流以及配套的构建验证手段。为什么需要 OpenAPI 同步一份活的 API 契约Windmill 是一个以脚本为原语的自动化平台其全部前端、CLI、各类 SDKtypescript-client、python-client、go-client、rust-client都围绕 HTTP API 工作。这份 API 的权威契约就是 OpenAPI 规范文件backend/windmill-api/openapi.yaml主 OpenAPI 规范当前为 OpenAPI 3.0.3覆盖全部 REST 端点仓库当前版本约 3.6 万行、865 个 operationIdinfo.version为1.809.0。openflow.openapi.yamlFlow工作流专用 OpenAPI 定义描述OpenFlow、FlowValue、FlowModule等流结构 Schema。这两份文件并非一次性生成的静态文档而是与 backend/windmill-api/src/ 下的路由处理器必须保持同步的活契约任何端点新增、响应结构调整、Flow 字段变更如果不同步更新规范文件客户端生成器与下游消费者就会拿到过时的类型。这就是openapi-syncAgent 存在的意义——它是仓库中专门负责Rust 实现 ↔ OpenAPI 规范双向对齐的工程角色。核心文件地图同步工作要盯住哪些位置同步一份 API 变更需要同时在四个层面定位事实来源文件/目录作用backend/windmill-api/src/API 路由处理器按领域组织scripts、flows、workspaces、users、jobs等是端点定义的事实来源backend/windmill-common/src/共享数据结构与类型定义决定请求/响应 Schema 的形状backend/summarized_schema.txt数据库模式的汇总参考用于理解数据模型与字段来源backend/windmill-api/openapi.yaml 与 openflow.openapi.yaml需要被更新的目标规范文件值得注意openapi-syncAgent 的描述中把openflow.openapi.yaml定位在backend/windmill-api/目录下但在当前仓库中该文件实际位于仓库根目录即 openflow.openapi.yaml同步时请以仓库内的真实路径为准。此外windmill-api下还有两个由构建脚本派生的产物backend/windmill-api/openapi-deref.yaml解引用后的 YAML与 backend/windmill-api/openapi-deref.json解引用后的 JSON它们由 backend/windmill-api/build_openapi.sh 自动生成不要手工编辑。同步工作流四步完成一次 API 契约更新第一步识别变更范围先确定本次代码改动影响了哪些 API 面windmill-api中新增、修改或删除了路由处理器请求/响应结构体Rust struct发生了变化Flow 数据结构或相关类型被修改认证要求发生变化。典型场景如新增POST /api/w/{workspace}/templates端点、给GET /api/w/{workspace}/flows的响应增加versions数组、或给FlowValue增加retry_policy字段——这些都应触发同步。第二步分析端点实现细节对每个受影响的端点从源码中提取以下信息HTTP 方法与完整路径路径参数、查询参数与请求体 Schema响应 Schema 与状态码认证要求所属标签tags与分组。这些信息直接来自windmill-api中对应的路由 handler 及其引用的 struct 定义而不是凭印象猜测。第三步更新 OpenAPI 文件在paths中新增或修改路径定义operationId 要准确在components中新增或更新 Schema 定义检查所有$ref引用是否正确与既有文件的命名风格保持一致。第四步验证变更确保 YAML 语法合法且遵循 OpenAPI 3.0 规范。仓库提供了自动化手段见下文构建与验证一节也可以在提交前用 OpenAPI 校验器如 Redocly做语法与结构校验。Windmill 的 OpenAPI 编写约定openapi-sync对规范文件有明确的风格约束这些约定在现有 openapi.yaml 中已有大量实例可循operationId使用 camelCase 的描述性命名如createScript、listFlows、updateWorkspaceSettings。仓库实际例子包括backendVersionGET /version、getHealthStatusGET /health/status等。tags按领域分组端点如scripts、flows、workspaces、users、settings、health。Schema 命名使用 PascalCase且与 Rust struct 名称保持一致便于在源码与规范之间双向检索。路径参数工作区 ID 统一写作{workspace}与既有模式保持一致。仓库的路由树中工作区相关端点都挂在{workspace_id}前缀之下见下文。安全声明绝大多数端点要求 Bearer Token 认证需声明相应的 security 要求。从 Rust 到 OpenAPI 的类型映射同步工作最核心的机械性部分是把 Rust 类型翻译成 OpenAPI Schema。openapi-sync给出的映射规则如下Rust 类型OpenAPI SchemaString/strtype: stringi32、i64type: integer附相应formatf32、f64type: numberbooltype: booleanVecTtype: arrayitemsOptionT属性不出现在required数组中HashMapK, Vtype: objectadditionalProperties枚举Enumstype: stringenum数组自定义结构体$ref指向 Schema 定义这套映射在 openflow.openapi.yaml 中体现得非常直观FlowValue的modules字段是type: arrayitems引用FlowModulecache_ttl、priority等数值字段映射为type: numbersame_worker、preserve_step_tags等布尔开关映射为type: boolean可选的failure_module、preprocessor_module则引用FlowModule且不强制要求。每个字段都带description这正是文档要全面这一职责的落地表现。从源码看 Windmill 的 API 结构规范文件背后的路由树要正确书写路径先要理解后端路由是如何组织的。在 backend/windmill-api/src/lib.rs 的run_server中所有路由被嵌套在/api前缀之下对应规范文件servers中声明的url: /api其主干结构为全局路由如/version、/health/status、/workspaces、/users、/settings、/jobs、/tokens工作区作用域路由统一嵌套在/w/{workspace_id}下按领域拆分/acls、/apps、/audit、/flows、/groups、/jobs、/scripts、/resources、/variables、/workspaces、/schedules、/workers等免认证端点*_u后缀与*_unauthed服务单独挂载如/w/{workspace_id}/jobs_u、/scripts_u、/settings_u安全相关端点/auth、/oidc、/saml、/scim、/tokens拥有独立的路由挂载点。规范的security段声明了全局安全方案并在components.securitySchemes中定义见 openapi.yaml 第 25949 行附近security: - bearerAuth: [] - cookieAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer cookieAuth: type: apiKey in: cookie name: token这意味着默认情况下端点需要 Bearer Token 或会话 Cookie 认证而像GET /health/status这类公开端点则在路径级显式声明security: []以覆盖全局默认。同步新端点时务必判断它是否需要这种覆盖声明。Flow 相关变更双文件同步当改动涉及 Flow 结构如给FlowValue增加字段、调整FlowModule定义时需要同时更新两份文件主规范 openapi.yaml 中与 Flow 相关的路径定义与引用以及 openflow.openapi.yaml 中components.schemas下的OpenFlow、FlowValue、FlowModule等定义。后者的职责是独立描述 OpenFlow 数据格式paths: {}为空纯 Schema 定义供 Flow 编辑器、导入导出与前端使用。FlowValue中modules、failure_module、preprocessor_module、concurrent_limit、debounce_delay_s、cache_ttl、flow_env支持$var:path与$res:path特殊引用等字段都在这份文件中被逐一文档化改动时必须保持两份文件的一致性。构建与验证用 Redocly 派生解引用产物规范文件的合法性验证与产物生成由 backend/windmill-api/build_openapi.sh 完成。该脚本的核心流程是npx redocly/openapi-clilatest bundle openapi.yaml openapi-bundled.yaml npx redocly/openapi-clilatest bundle openapi-bundled.yaml --ext yaml -d openapi-deref.yaml npx redocly/openapi-clilatest bundle openapi-bundled.yaml --ext json openapi-deref.json rm openapi-bundled.yaml它先对openapi.yaml做 bundle合并内外部引用再分别产出解引用后的 YAML 与 JSON 版本。这意味着主规范文件可以自由使用$ref与跨文件引用Redocly 负责解析合并openapi-deref.*是给下游工具链用的扁平化产物永远不要手工编辑修改openapi.yaml后应运行该脚本验证 bundle 能成功完成——这一步同时就是 OpenAPI 语法的强校验。同步维护的注意事项清单openapi-sync明确要求同步时遵守以下纪律这也是写规范文件时的通用最佳实践保留既有文档与描述更新端点时不要覆盖已有的 summary、description 与示例只在必要时增补维护向后兼容性提示当 Schema 变更可能破坏既有消费者时在描述中保留兼容性警告善用示例值在有助于理解的地方补充 example降低下游接入成本风格一致严格沿用 YAML 文件既有的缩进与格式风格避免无谓的 diff完成时汇报变更完成后应总结哪些文件被修改、新增/调整了哪些 Schema并指出下游消费者需要关注的契约变化。以本文的方法论为基准任何一次windmill-api的端点演进——无论是新增模板管理接口、扩展 Flow 列表响应还是给FlowValue增加重试策略字段——都能以识别 → 分析 → 更新 → 验证的闭环安全地落到 openapi.yaml 与 openflow.openapi.yaml 中让 Rust 实现与 API 契约始终保持一致。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 11:51:34 · 阅读 1.2k Windmill 仓库 OpenAPI 规范同步指南：让 Rust 后端 API 与 openapi.yaml 始终一致
Windmill 仓库 OpenAPI 规范同步指南让 Rust 后端 API 与 openapi.yaml 始终一致【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill本文是一份面向 Windmill 开源仓库维护者与二次开发者的 API 文档工程指南。它围绕仓库中openapi-syncAgent 的工作方法论展开系统讲解如何在 Rust 后端windmill-apicrate增删改 API 端点、修改请求/响应结构体、或调整 Flow 数据结构时同步维护两份 OpenAPI 规范文件保证契约、客户端生成与文档的一致性。读完本文你将掌握 Windmill 的 OpenAPI 文件布局、从 Rust 实现到 OpenAPI Schema 的类型映射规则、规范化的同步工作流以及配套的构建验证手段。为什么需要 OpenAPI 同步一份活的 API 契约Windmill 是一个以脚本为原语的自动化平台其全部前端、CLI、各类 SDKtypescript-client、python-client、go-client、rust-client都围绕 HTTP API 工作。这份 API 的权威契约就是 OpenAPI 规范文件backend/windmill-api/openapi.yaml主 OpenAPI 规范当前为 OpenAPI 3.0.3覆盖全部 REST 端点仓库当前版本约 3.6 万行、865 个 operationIdinfo.version为1.809.0。openflow.openapi.yamlFlow工作流专用 OpenAPI 定义描述OpenFlow、FlowValue、FlowModule等流结构 Schema。这两份文件并非一次性生成的静态文档而是与 backend/windmill-api/src/ 下的路由处理器必须保持同步的活契约任何端点新增、响应结构调整、Flow 字段变更如果不同步更新规范文件客户端生成器与下游消费者就会拿到过时的类型。这就是openapi-syncAgent 存在的意义——它是仓库中专门负责Rust 实现 ↔ OpenAPI 规范双向对齐的工程角色。核心文件地图同步工作要盯住哪些位置同步一份 API 变更需要同时在四个层面定位事实来源文件/目录作用backend/windmill-api/src/API 路由处理器按领域组织scripts、flows、workspaces、users、jobs等是端点定义的事实来源backend/windmill-common/src/共享数据结构与类型定义决定请求/响应 Schema 的形状backend/summarized_schema.txt数据库模式的汇总参考用于理解数据模型与字段来源backend/windmill-api/openapi.yaml 与 openflow.openapi.yaml需要被更新的目标规范文件值得注意openapi-syncAgent 的描述中把openflow.openapi.yaml定位在backend/windmill-api/目录下但在当前仓库中该文件实际位于仓库根目录即 openflow.openapi.yaml同步时请以仓库内的真实路径为准。此外windmill-api下还有两个由构建脚本派生的产物backend/windmill-api/openapi-deref.yaml解引用后的 YAML与 backend/windmill-api/openapi-deref.json解引用后的 JSON它们由 backend/windmill-api/build_openapi.sh 自动生成不要手工编辑。同步工作流四步完成一次 API 契约更新第一步识别变更范围先确定本次代码改动影响了哪些 API 面windmill-api中新增、修改或删除了路由处理器请求/响应结构体Rust struct发生了变化Flow 数据结构或相关类型被修改认证要求发生变化。典型场景如新增POST /api/w/{workspace}/templates端点、给GET /api/w/{workspace}/flows的响应增加versions数组、或给FlowValue增加retry_policy字段——这些都应触发同步。第二步分析端点实现细节对每个受影响的端点从源码中提取以下信息HTTP 方法与完整路径路径参数、查询参数与请求体 Schema响应 Schema 与状态码认证要求所属标签tags与分组。这些信息直接来自windmill-api中对应的路由 handler 及其引用的 struct 定义而不是凭印象猜测。第三步更新 OpenAPI 文件在paths中新增或修改路径定义operationId 要准确在components中新增或更新 Schema 定义检查所有$ref引用是否正确与既有文件的命名风格保持一致。第四步验证变更确保 YAML 语法合法且遵循 OpenAPI 3.0 规范。仓库提供了自动化手段见下文构建与验证一节也可以在提交前用 OpenAPI 校验器如 Redocly做语法与结构校验。Windmill 的 OpenAPI 编写约定openapi-sync对规范文件有明确的风格约束这些约定在现有 openapi.yaml 中已有大量实例可循operationId使用 camelCase 的描述性命名如createScript、listFlows、updateWorkspaceSettings。仓库实际例子包括backendVersionGET /version、getHealthStatusGET /health/status等。tags按领域分组端点如scripts、flows、workspaces、users、settings、health。Schema 命名使用 PascalCase且与 Rust struct 名称保持一致便于在源码与规范之间双向检索。路径参数工作区 ID 统一写作{workspace}与既有模式保持一致。仓库的路由树中工作区相关端点都挂在{workspace_id}前缀之下见下文。安全声明绝大多数端点要求 Bearer Token 认证需声明相应的 security 要求。从 Rust 到 OpenAPI 的类型映射同步工作最核心的机械性部分是把 Rust 类型翻译成 OpenAPI Schema。openapi-sync给出的映射规则如下Rust 类型OpenAPI SchemaString/strtype: stringi32、i64type: integer附相应formatf32、f64type: numberbooltype: booleanVecTtype: arrayitemsOptionT属性不出现在required数组中HashMapK, Vtype: objectadditionalProperties枚举Enumstype: stringenum数组自定义结构体$ref指向 Schema 定义这套映射在 openflow.openapi.yaml 中体现得非常直观FlowValue的modules字段是type: arrayitems引用FlowModulecache_ttl、priority等数值字段映射为type: numbersame_worker、preserve_step_tags等布尔开关映射为type: boolean可选的failure_module、preprocessor_module则引用FlowModule且不强制要求。每个字段都带description这正是文档要全面这一职责的落地表现。从源码看 Windmill 的 API 结构规范文件背后的路由树要正确书写路径先要理解后端路由是如何组织的。在 backend/windmill-api/src/lib.rs 的run_server中所有路由被嵌套在/api前缀之下对应规范文件servers中声明的url: /api其主干结构为全局路由如/version、/health/status、/workspaces、/users、/settings、/jobs、/tokens工作区作用域路由统一嵌套在/w/{workspace_id}下按领域拆分/acls、/apps、/audit、/flows、/groups、/jobs、/scripts、/resources、/variables、/workspaces、/schedules、/workers等免认证端点*_u后缀与*_unauthed服务单独挂载如/w/{workspace_id}/jobs_u、/scripts_u、/settings_u安全相关端点/auth、/oidc、/saml、/scim、/tokens拥有独立的路由挂载点。规范的security段声明了全局安全方案并在components.securitySchemes中定义见 openapi.yaml 第 25949 行附近security: - bearerAuth: [] - cookieAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer cookieAuth: type: apiKey in: cookie name: token这意味着默认情况下端点需要 Bearer Token 或会话 Cookie 认证而像GET /health/status这类公开端点则在路径级显式声明security: []以覆盖全局默认。同步新端点时务必判断它是否需要这种覆盖声明。Flow 相关变更双文件同步当改动涉及 Flow 结构如给FlowValue增加字段、调整FlowModule定义时需要同时更新两份文件主规范 openapi.yaml 中与 Flow 相关的路径定义与引用以及 openflow.openapi.yaml 中components.schemas下的OpenFlow、FlowValue、FlowModule等定义。后者的职责是独立描述 OpenFlow 数据格式paths: {}为空纯 Schema 定义供 Flow 编辑器、导入导出与前端使用。FlowValue中modules、failure_module、preprocessor_module、concurrent_limit、debounce_delay_s、cache_ttl、flow_env支持$var:path与$res:path特殊引用等字段都在这份文件中被逐一文档化改动时必须保持两份文件的一致性。构建与验证用 Redocly 派生解引用产物规范文件的合法性验证与产物生成由 backend/windmill-api/build_openapi.sh 完成。该脚本的核心流程是npx redocly/openapi-clilatest bundle openapi.yaml openapi-bundled.yaml npx redocly/openapi-clilatest bundle openapi-bundled.yaml --ext yaml -d openapi-deref.yaml npx redocly/openapi-clilatest bundle openapi-bundled.yaml --ext json openapi-deref.json rm openapi-bundled.yaml它先对openapi.yaml做 bundle合并内外部引用再分别产出解引用后的 YAML 与 JSON 版本。这意味着主规范文件可以自由使用$ref与跨文件引用Redocly 负责解析合并openapi-deref.*是给下游工具链用的扁平化产物永远不要手工编辑修改openapi.yaml后应运行该脚本验证 bundle 能成功完成——这一步同时就是 OpenAPI 语法的强校验。同步维护的注意事项清单openapi-sync明确要求同步时遵守以下纪律这也是写规范文件时的通用最佳实践保留既有文档与描述更新端点时不要覆盖已有的 summary、description 与示例只在必要时增补维护向后兼容性提示当 Schema 变更可能破坏既有消费者时在描述中保留兼容性警告善用示例值在有助于理解的地方补充 example降低下游接入成本风格一致严格沿用 YAML 文件既有的缩进与格式风格避免无谓的 diff完成时汇报变更完成后应总结哪些文件被修改、新增/调整了哪些 Schema并指出下游消费者需要关注的契约变化。以本文的方法论为基准任何一次windmill-api的端点演进——无论是新增模板管理接口、扩展 Flow 列表响应还是给FlowValue增加重试策略字段——都能以识别 → 分析 → 更新 → 验证的闭环安全地落到 openapi.yaml 与 openflow.openapi.yaml 中让 Rust 实现与 API 契约始终保持一致。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考