用途
该技能用于在 Nango 项目中为全新的第三方服务商(provider)添加集成支持。它覆盖两件事:一是服务商认证与代理配置,二是配套文档的创建与导航登记。适用场景包括:为全新服务商添加支持、为尚不存在的集成创建配置和文档,以及用户提出“add support for [provider]”“add [provider] integration”或“create documentation for [provider]”之类请求时。
不适用场景:迁移已有文档(应使用 nango-docs-migrator 代理)、编辑现有集成文档,以及一般性文档改动。
主要能力
-
服务商配置:在
packages/providers/providers.yaml中添加或更新条目,要求按 slug 字母顺序插入。支持的认证模式包括 API_KEY、BASIC、OAUTH1、OAUTH2、OAUTH2_CC、JWT、TWO_STEP、SIGNATURE。关键字段包括display_name、categories、auth_mode、authorization_url、token_url、proxy.base_url、proxy.headers、proxy.verification、connection_config、credentials、docs、setup_guide_url、docs_connect等。 -
凭证验证:仅 API_KEY、BASIC、JWT 三种模式需要在
proxy中配置 verification;其余模式(OAUTH2、OAUTH1、OAUTH2_CC、TWO_STEP、SIGNATURE)在 OAuth 流程中自动完成验证。建议选择最简单的验证端点(如/me、/user、/profile、/account),如支持 limit 参数设为 1,尽量使用 GET,保持最小化。 -
文档创建:按认证模式决定需要哪些文件:
- 所有模式都需要主页面
docs/api-integrations/[slug].mdx; - OAUTH2 与 OAUTH1 需要设置指南
docs/api-integrations/[slug]/how-to-register-your-own-[slug]-oauth-app.mdx; - 所有非 OAUTH2 模式需要连接指南
docs/api-integrations/[slug]/connect.mdx; - 带 connectionConfig 的 OAUTH2 同时需要设置指南和连接指南。
- 导航登记:在
docs/docs.json的 "APIs & Integrations" 分组中添加条目。预构建的 syncs 片段由自动化脚本生成,无需手动创建。
使用方式
执行顺序要求:始终先编辑 packages/providers/providers.yaml,再创建文档。创建文档前需收集:集成名称、slug、分类、认证类型、API base URL、官方 API 文档链接、OAuth 设置步骤(如适用)、connectionConfig 需要用户提供的值(如适用)。分类只能从给定清单中选择(accounting、analytics、ats、banking、cms、communication、crm、design、dev-tools、e-commerce、erp、gaming、hr、invoicing、knowledge-base、legal、marketing、mcp、other、payment、popular、productivity、search、social、sports、storage、support、surveys、ticketing、video),不得新建分类。
资料给出了各认证模式的完整 YAML 示例:API_KEY(slab)、OAUTH2 无 connectionConfig(acuity-scheduling)、OAUTH2 带 connectionConfig(accelo)、BASIC(private-api-basic)、OAUTH2_CC(adobe-umapi)、OAUTH1(garmin)、TWO_STEP(jamf-basic)、JWT(ghost)、SIGNATURE(emarsys)。主页面模板为 frontmatter 加“🚀 Quickstart”四步骤:创建集成、授权、调用 API,以及指南链接和 syncs 章节(模板在资料中被截断,后续步骤暂未提供)。
适用场景与限制
适用于在 Nango 生态中首次接入新服务商时的配置与文档搭建。限制与注意事项:必须遵循字母顺序插入 providers.yaml;分类只能使用允许清单;verification 仅适用于三种指定认证模式,且需保持请求轻量;预构建 syncs 片段不得手写;资料中主页面模板内容不完整,未给出的步骤与细节暂未提供。