ToolJet OpenAPI 数据源接入指南从 OpenAPI Spec 自动生成 REST API 查询【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetOpenAPI 是设计和描述 RESTful API 的标准规范。ToolJet 的 OpenAPI 数据源允许你直接上传 OpenAPI SpecJSON / YAML由平台自动解析并生成对应的 REST API 操作operation无需手写请求 URL、方法或鉴权逻辑。读完本文你将掌握在 ToolJet 中创建 OpenAPI 连接、配置 Basic Auth / API Key / Bearer Token / OAuth 2.0 等多种鉴权、执行自动生成的操作并读取返回结果以及理解其底层实现原理的完整方案。OpenAPI 数据源是什么OpenAPI前身为 Swagger是一套用于设计、编写、消费 RESTful API 的规范它用机器可读的 JSON 或 YAML 文件描述接口的路径、HTTP 方法、参数、请求体与响应结构。ToolJet 将这一标准与低代码查询能力结合你提供 SpecToolJet 帮你生成查询操作。从源码看OpenAPI 数据源是 ToolJet 插件体系中的一个标准查询插件其实现位于 plugins/packages/openapi/lib/index.ts插件清单定义在 plugins/packages/openapi/lib/manifest.json。它的工作方式非常直接读取 Spec 中的paths字段将每个路径下的 HTTP 方法get、post、put、patch、delete、head、options解析为一个个独立操作每个操作在查询面板中以“选择操作”的方式呈现你只需要选中并填写参数即可发起请求请求的发送基于gotHTTP 客户端并统一接入 ToolJet 的 SSRF 防护与鉴权处理管线。创建 OpenAPI 数据源连接在 ToolJet 中建立 OpenAPI 连接有两种入口与所有数据源一致点击查询面板上的 Add new Data source按钮或者通过 ToolJet 仪表盘导航到 数据源总览 页面。连接的创建基于 OpenAPI 规范文件你需要提供一份 Spec 的定义内容definition。根据 manifest.json 中的required字段definition是唯一必填项host是可选项用于覆盖 Spec 中定义的服务器地址帮助文本明确写着 Overrides the host defined in the OpenAPI spec。格式约束OpenAPI 数据源仅接受JSON和YAML两种格式的 Spec官方文档原话为 accepts specifications only inJSONandYAMLformats。前端会通过react-component-openapi-validator类型的表单组件对上传的 Spec 做实时校验。支持的鉴权方式连接配置支持以下鉴权类型鉴权方式说明Basic Auth用户名 密码username/password字段API Key通过api_keys与auth_key配置键名及放置位置Bearer Tokenbearer_token字段请求时自动添加Authorization: Bearer token头OAuth 2.0客户端凭证 / 授权码模式含client_id、client_secret、auth_url、access_token_url等同一份 Spec 中如果包含多种安全要求也是支持的即多重鉴权场景。从 manifest.json 可以看到password、bearer_token、client_secret均标记为encrypted: true说明这些敏感字段在服务端是加密存储的。其余默认配置项还包括grant_type默认authorization_codeadd_token_to默认header即将 token 放入请求头header_prefix默认Bearer注意含尾随空格client_auth默认header各类headers、custom_query_params、custom_auth_params、access_token_custom_headers以键值对数组形式配置。发起 OpenAPI 查询数据源创建完成后发起一次查询只需四步点击编辑器底部查询管理器的 Add按钮选择上一步创建的OpenAPI数据源在下拉列表中选择期望的操作Operation点击Preview预览输出或点击Run触发查询。注意所有操作都会根据 Spec 自动生成每个操作彼此独立Operations will be automatically generated from the specifications, and each operation will be distinct from others。查询字段查询表单包含两个核心字段Host主机地址可选若填写则覆盖 Spec 中定义的服务端 host。Operation从 Spec 中解析出的具体接口操作如GET /users、POST /orders。选中某个操作后表单会根据该操作在 Spec 中的定义展开对应的参数输入区路径参数、查询参数、请求头、请求体这些参数最终汇入查询选项的params对象其中包含request请求体、query查询参数、header请求头、path路径参数四组。底层执行原理一次查询是如何被处理的如果你好奇选择操作 → 点击 Run背后发生了什么可以从 plugins/packages/openapi/lib/index.ts 的run方法看起其处理流程如下拼接 URL 与解析路径参数resolvePathParams将路径中的{key}占位符替换为实际的路径参数值最终 URL 为sourceOptions.host || host与解析后的路径拼接而成。SSRF 防护发送请求前调用validateUrlForSSRF校验目标 URL随后通过getSSRFProtectionOptions注入自定义 DNS 解析与重定向校验防止服务器端请求伪造攻击。组装请求选项非 GET 操作且存在请求体时会先经过parseRequest尝试把字符串解析为 JSON与sanitizeObject剔除空字符串字段再以 JSON 请求体发送查询参数放入searchParams请求头放入headers。按鉴权类型注入凭证调用公共模块 plugins/packages/common/lib/oauth.ts 中的validateAndSetRequestOptionsBasedOnAuthType根据auth_type分发到不同处理函数bearer自动添加Authorization: Bearer token请求头见handleBearerAuthenticationbasic注入 Basic Auth 凭证apiKey通过resolveApiKeyParams将 API Key 按配置放入 header、query 或 cookieoauth2/oauth走handleOAuthAuthentication必要时触发刷新 token 流程。发送请求并规范化结果使用got发送请求若响应 Content-Type 为application/json则自动解析为对象否则保留原始文本。返回结果统一包含data、request请求 URL / 方法 / 头 / 参数、response响应体与状态码、responseHeaders。错误处理遇到 HTTP 错误时返回结构化的requestObject/responseObject/responseHeaders供前端展示OAuth 2.0 场景下若返回 401会抛出OAuthUnauthorizedClientError触发 token 刷新重试机制其余异常统一包装为QueryError。值得一提的是OpenAPI 插件还实现了listTables方法见 index.ts它负责从 Spec 的paths中枚举所有端点过滤出受支持的 7 种 HTTP 方法get、post、put、patch、delete、head、options并提取每个操作的summary与operationId——这正是查询面板中操作下拉列表的数据来源。服务端对 OpenAPI 数据源的特殊处理在 ToolJet 服务端OpenAPI 数据源属于非插件kind型数据源因此有几处专门的逻辑在 server/src/modules/data-sources/service.ts 中当dataSource.kind openapi时返回给前端的数据会做 key 脱驼峰化decamelize同时保留spec字段原样decamelizedOptions[spec] spec避免 Spec 内容被改写。在 server/src/modules/data-queries/util.service.ts 中openapi被归入需要特殊查询逻辑的数据源类型列表。插件市场支持在插件目录下附带openapi-specs/目录存放.yaml/.json规范文件由 server/src/modules/plugins/util.service.ts 自动收集并作为市场资产提供说明 OpenAPI Spec 也可以作为插件资产的一部分被分发和引用。与其他 REST 数据源的关系如果你之前使用过 ToolJet 的 REST API 数据源会发现在鉴权配置Basic / Bearer / API Key / OAuth 2.0、SSRF 防护、OAuth token 刷新等能力上两者高度一致——OpenAPI 数据源正是复用了 plugins/packages/common/lib/oauth.ts 与 plugins/packages/common/lib/ssrf-protection.ts 中的公共实现。二者的核心区别在于REST API 数据源手动指定方法、URL、请求头与请求体灵活但需要你理解接口细节OpenAPI 数据源从 Spec 自动生成操作列表把找接口、写请求变成选操作、填参数特别适合接口数量多、且已有规范文档的团队。从测试状态看plugins/packages/openapi/tests/index.js 目前以it.todo(needs tests)占位尚未补充正式的单元测试如果你计划为该插件贡献代码可以以此为切入点。总结ToolJet 的 OpenAPI 数据源把行业标准的 OpenAPI 规范与低代码查询能力打通上传 Spec 即可获得一组自动生成、相互独立的 REST 操作支持 Basic Auth、API Key、Bearer Token 与 OAuth 2.0含多重鉴权并在底层集成了 SSRF 防护、参数自动解析、JSON 响应智能解析与 OAuth token 刷新等工程化能力。对于拥有成熟 API 规范、希望在内部工具中快速消费这些接口的团队这是一个开箱即用、成本极低的接入路径。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet OpenAPI 数据源接入指南：从 OpenAPI Spec 自动生成 REST API 查询
ToolJet OpenAPI 数据源接入指南从 OpenAPI Spec 自动生成 REST API 查询【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetOpenAPI 是设计和描述 RESTful API 的标准规范。ToolJet 的 OpenAPI 数据源允许你直接上传 OpenAPI SpecJSON / YAML由平台自动解析并生成对应的 REST API 操作operation无需手写请求 URL、方法或鉴权逻辑。读完本文你将掌握在 ToolJet 中创建 OpenAPI 连接、配置 Basic Auth / API Key / Bearer Token / OAuth 2.0 等多种鉴权、执行自动生成的操作并读取返回结果以及理解其底层实现原理的完整方案。OpenAPI 数据源是什么OpenAPI前身为 Swagger是一套用于设计、编写、消费 RESTful API 的规范它用机器可读的 JSON 或 YAML 文件描述接口的路径、HTTP 方法、参数、请求体与响应结构。ToolJet 将这一标准与低代码查询能力结合你提供 SpecToolJet 帮你生成查询操作。从源码看OpenAPI 数据源是 ToolJet 插件体系中的一个标准查询插件其实现位于 plugins/packages/openapi/lib/index.ts插件清单定义在 plugins/packages/openapi/lib/manifest.json。它的工作方式非常直接读取 Spec 中的paths字段将每个路径下的 HTTP 方法get、post、put、patch、delete、head、options解析为一个个独立操作每个操作在查询面板中以“选择操作”的方式呈现你只需要选中并填写参数即可发起请求请求的发送基于gotHTTP 客户端并统一接入 ToolJet 的 SSRF 防护与鉴权处理管线。创建 OpenAPI 数据源连接在 ToolJet 中建立 OpenAPI 连接有两种入口与所有数据源一致点击查询面板上的 Add new Data source按钮或者通过 ToolJet 仪表盘导航到 数据源总览 页面。连接的创建基于 OpenAPI 规范文件你需要提供一份 Spec 的定义内容definition。根据 manifest.json 中的required字段definition是唯一必填项host是可选项用于覆盖 Spec 中定义的服务器地址帮助文本明确写着 Overrides the host defined in the OpenAPI spec。格式约束OpenAPI 数据源仅接受JSON和YAML两种格式的 Spec官方文档原话为 accepts specifications only inJSONandYAMLformats。前端会通过react-component-openapi-validator类型的表单组件对上传的 Spec 做实时校验。支持的鉴权方式连接配置支持以下鉴权类型鉴权方式说明Basic Auth用户名 密码username/password字段API Key通过api_keys与auth_key配置键名及放置位置Bearer Tokenbearer_token字段请求时自动添加Authorization: Bearer token头OAuth 2.0客户端凭证 / 授权码模式含client_id、client_secret、auth_url、access_token_url等同一份 Spec 中如果包含多种安全要求也是支持的即多重鉴权场景。从 manifest.json 可以看到password、bearer_token、client_secret均标记为encrypted: true说明这些敏感字段在服务端是加密存储的。其余默认配置项还包括grant_type默认authorization_codeadd_token_to默认header即将 token 放入请求头header_prefix默认Bearer注意含尾随空格client_auth默认header各类headers、custom_query_params、custom_auth_params、access_token_custom_headers以键值对数组形式配置。发起 OpenAPI 查询数据源创建完成后发起一次查询只需四步点击编辑器底部查询管理器的 Add按钮选择上一步创建的OpenAPI数据源在下拉列表中选择期望的操作Operation点击Preview预览输出或点击Run触发查询。注意所有操作都会根据 Spec 自动生成每个操作彼此独立Operations will be automatically generated from the specifications, and each operation will be distinct from others。查询字段查询表单包含两个核心字段Host主机地址可选若填写则覆盖 Spec 中定义的服务端 host。Operation从 Spec 中解析出的具体接口操作如GET /users、POST /orders。选中某个操作后表单会根据该操作在 Spec 中的定义展开对应的参数输入区路径参数、查询参数、请求头、请求体这些参数最终汇入查询选项的params对象其中包含request请求体、query查询参数、header请求头、path路径参数四组。底层执行原理一次查询是如何被处理的如果你好奇选择操作 → 点击 Run背后发生了什么可以从 plugins/packages/openapi/lib/index.ts 的run方法看起其处理流程如下拼接 URL 与解析路径参数resolvePathParams将路径中的{key}占位符替换为实际的路径参数值最终 URL 为sourceOptions.host || host与解析后的路径拼接而成。SSRF 防护发送请求前调用validateUrlForSSRF校验目标 URL随后通过getSSRFProtectionOptions注入自定义 DNS 解析与重定向校验防止服务器端请求伪造攻击。组装请求选项非 GET 操作且存在请求体时会先经过parseRequest尝试把字符串解析为 JSON与sanitizeObject剔除空字符串字段再以 JSON 请求体发送查询参数放入searchParams请求头放入headers。按鉴权类型注入凭证调用公共模块 plugins/packages/common/lib/oauth.ts 中的validateAndSetRequestOptionsBasedOnAuthType根据auth_type分发到不同处理函数bearer自动添加Authorization: Bearer token请求头见handleBearerAuthenticationbasic注入 Basic Auth 凭证apiKey通过resolveApiKeyParams将 API Key 按配置放入 header、query 或 cookieoauth2/oauth走handleOAuthAuthentication必要时触发刷新 token 流程。发送请求并规范化结果使用got发送请求若响应 Content-Type 为application/json则自动解析为对象否则保留原始文本。返回结果统一包含data、request请求 URL / 方法 / 头 / 参数、response响应体与状态码、responseHeaders。错误处理遇到 HTTP 错误时返回结构化的requestObject/responseObject/responseHeaders供前端展示OAuth 2.0 场景下若返回 401会抛出OAuthUnauthorizedClientError触发 token 刷新重试机制其余异常统一包装为QueryError。值得一提的是OpenAPI 插件还实现了listTables方法见 index.ts它负责从 Spec 的paths中枚举所有端点过滤出受支持的 7 种 HTTP 方法get、post、put、patch、delete、head、options并提取每个操作的summary与operationId——这正是查询面板中操作下拉列表的数据来源。服务端对 OpenAPI 数据源的特殊处理在 ToolJet 服务端OpenAPI 数据源属于非插件kind型数据源因此有几处专门的逻辑在 server/src/modules/data-sources/service.ts 中当dataSource.kind openapi时返回给前端的数据会做 key 脱驼峰化decamelize同时保留spec字段原样decamelizedOptions[spec] spec避免 Spec 内容被改写。在 server/src/modules/data-queries/util.service.ts 中openapi被归入需要特殊查询逻辑的数据源类型列表。插件市场支持在插件目录下附带openapi-specs/目录存放.yaml/.json规范文件由 server/src/modules/plugins/util.service.ts 自动收集并作为市场资产提供说明 OpenAPI Spec 也可以作为插件资产的一部分被分发和引用。与其他 REST 数据源的关系如果你之前使用过 ToolJet 的 REST API 数据源会发现在鉴权配置Basic / Bearer / API Key / OAuth 2.0、SSRF 防护、OAuth token 刷新等能力上两者高度一致——OpenAPI 数据源正是复用了 plugins/packages/common/lib/oauth.ts 与 plugins/packages/common/lib/ssrf-protection.ts 中的公共实现。二者的核心区别在于REST API 数据源手动指定方法、URL、请求头与请求体灵活但需要你理解接口细节OpenAPI 数据源从 Spec 自动生成操作列表把找接口、写请求变成选操作、填参数特别适合接口数量多、且已有规范文档的团队。从测试状态看plugins/packages/openapi/tests/index.js 目前以it.todo(needs tests)占位尚未补充正式的单元测试如果你计划为该插件贡献代码可以以此为切入点。总结ToolJet 的 OpenAPI 数据源把行业标准的 OpenAPI 规范与低代码查询能力打通上传 Spec 即可获得一组自动生成、相互独立的 REST 操作支持 Basic Auth、API Key、Bearer Token 与 OAuth 2.0含多重鉴权并在底层集成了 SSRF 防护、参数自动解析、JSON 响应智能解析与 OAuth token 刷新等工程化能力。对于拥有成熟 API 规范、希望在内部工具中快速消费这些接口的团队这是一个开箱即用、成本极低的接入路径。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考