Nango 集成文档编写指南从 Quickstart 主页面到 providers.yaml 的完整工作流【免费下载链接】nangoBuild product integrations with AI.项目地址: https://gitcode.com/GitHub_Trending/na/nango导读本文是 Nango 开源仓库内creating-integration-docs技能的完整拆解它定义了为 Nango 添加或编辑某个第三方 API 集成文档时应遵循的既定模式一个带 4 步 Quickstart 的主集成页面、独立的 OAuth 应用注册设置指南、可选的连接指南以及docs/docs.json与packages/providers/providers.yaml的配套配置。读完本文你将掌握 Nango 集成文档的完整文件骨架、每类文件的 MDX 模板、导航与 provider 元数据的更新方式并能对照仓库中真实的 Slack 集成示例逐文件落地一套可运行、可被mintlify broken-links校验通过的文档。一、技能定位何时使用、何时禁用该技能用于 Nango 集成文档的创建与维护覆盖以下场景为一个全新的集成添加文档为尚不存在的集成创建文档用户提出为某个集成添加文档或创建某个集成的文档编辑既有集成的主页面、设置指南或连接指南。需要明确的是它不适用于两类工作迁移既有文档应交给nango-docs-migratoragent和一般性的文档改动。这一边界保证了集成文档的产出物始终收敛到同一套模式避免与站点级文档维护流程互相干扰。二、必须先遵守的 Docs 约定来源docs/AGENTS.mddocs/AGENTS.md是整个文档站约定的事实来源site-wide source of truth该技能创建的每一页都必须服从它。其中对集成页面最容易踩坑的三条规则是正文标题从 H2 开始——frontmatter 中的title就是页面唯一的 H1因此connect.mdx与设置指南必须以## Overview开头绝不能出现# Overview。Mintlify 会把 frontmatter 的title渲染为页面唯一 H1正文再出现#会产生第二个 H1破坏屏幕阅读器与 SEO 的文档大纲。docs/AGENTS.md还提供了自查命令rg -n ^# changed-mdx-files凡是命中行要么是需要降级的正文 H1要么是代码块中的#注释应原样保留。降级带##子标题的标题时子标题也要同步降级以保持层级完整。标题使用句子大小写sentence case——页面标题、侧边栏标题、卡片标题与正文标题统一使用句子大小写专有名词与缩写保留标准写法Nango、MCP、API、OAuth、CI/CD、GDPR。每次改动涉及标题、页面路径或内部链接后必须从docs/目录运行链接校验cd docs mintlify broken-links扫描必须以success no broken links found结束。注意Mintlify 的 MDX 解析器会把{...}当作 JavaScript 表达式## Heading {#anchor}这类锚点语法会导致整个站点的链接校验在扫描前就中止若要固定锚点应使用标题上方的一行内联 HTML 锚点a idmy-anchor/a。此外docs/AGENTS.md还强调指引读者操作 Nango 控制台时应按 tab 的可见名称引用如 Integrations、Connections、Logs而不是链接到 dashboard URL——因为 URL 中的环境标识在不同账号间不可预测。这也是本文所有示例的表述方式。三、快速参考集成文档涉及的文件与职责文件路径用途主页面docs/api-integrations/[slug].mdxQuickstart 指南链接 syncs 区块设置指南docs/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app.mdxOAuth 应用注册步骤连接指南docs/api-integrations/[slug]/connect.mdx可选自定义连接界面Syncs 片段snippets/generated/[slug]/PreBuiltUseCases.mdx自动生成或空状态导航配置docs/docs.json加入 900 APIs Integrations 分组Provider 配置packages/providers/providers.yaml添加docs与setup_guide_url其中[slug]是集成的 URL 友好标识一律使用小写加连字符格式如google-calendar而不是googleCalendar。四、开工前收集的必要信息创建文档前必须先收集 6 项信息缺一不可集成名称如 Slack、Salesforce集成 slug如slack、salesforce、google-calendar认证类型OAuth2、API Key、Basic Auth——直接决定设置指南的模板变体API base URL用于 proxy 示例API 文档 URL官方文档链接OAuth 设置步骤如果是 OAuth如何获取凭据。五、三份文件模板详解5.1 主集成页面Main Integration Page路径docs/api-integrations/[slug].mdx模板由 frontmatter 与四个正文区块组成--- title: [Integration Name] sidebarTitle: [Integration Name] description: Integrate your application with the [Integration Name] API --- ## Quickstart Connect to [Integration Name] with Nango and see data flow in 2 minutes. Steps Step titleCreate the integration In Nango (free signup), go to Integrations - _Configure New Integration_ - _[Integration Name]_. /Step Step titleAuthorize [Integration Name] Go to Connections - _Add Test Connection_ - _Authorize_, then log in to [Integration Name]. Later, youll let your users do the same directly from your app. /Step Step titleCall the [Integration Name] API Lets make your first request to the [Integration Name] API. Replace the placeholders below with your Environment API key, integration ID, and connection ID: Tabs Tab titlecURL bash curl https://api.nango.dev/proxy/[example-endpoint] \ -H Authorization: Bearer NANGO-API-KEY \ -H Provider-Config-Key: INTEGRATION-ID \ -H Connection-Id: CONNECTION-ID /Tab Tab titleNode Install Nangos backend SDK with npm i nangohq/node. Then run: typescript import { Nango } from nangohq/node; const nango new Nango({ apiKey: NANGO-API-KEY }); const res await nango.get({ endpoint: /[example-endpoint], providerConfigKey: INTEGRATION-ID, connectionId: CONNECTION-ID }); console.log(res.data); /Tab /Tabs Or fetch credentials with the Node SDK or the connection HTTP API. ✅ Youre connected! Check the Logs tab in Nango to inspect requests. /Step Step titleImplement Nango in your app Follow our quickstart to integrate Nango in your app. To obtain your own production credentials, follow the setup guide linked below. /Step /Steps ## [Integration Name] Integration Guides Nango maintained guides for common use cases. - [How to register your own [Integration Name] API OAuth app](/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app) Register an OAuth app with [Integration Name] and obtain credentials to connect it to Nango Official docs: [[Integration Name] API docs]([API_DOCS_URL]) ## Pre-built syncs actions for [Integration Name] Enable them in your dashboard. Extend and customize to fit your needs. import PreBuiltUseCases from /snippets/generated/[slug]/PreBuiltUseCases.mdx PreBuiltUseCases /模板要点解读Quickstart 的 4 个Step是固定结构创建集成 → 授权 → 首次调用 API → 在应用中落地 Nango。第三步用Tabs同时给出 cURL 与 Nodenangohq/nodeSDK 的Nango.get两种调用方式并提示可通过 SDK 或 HTTP API 直接拉取连接凭据。proxy 调用依赖三个请求头Authorization: Bearer NANGO-API-KEYEnvironment API key、Provider-Config-Key集成 ID、Connection-Id连接 ID。这是 Nango 代理层把请求路由到正确 provider 与连接的关键三要素。指南链接Guides区块中指南描述需要跟在链接后面且链接闭合括号)之后必须有两个空格才能实现换行渲染。最底部通过import PreBuiltUseCases from /snippets/generated/[slug]/PreBuiltUseCases.mdx引入同步/动作片段与snippets/generated/目录联动。5.2 设置指南Setup Guide路径docs/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app.mdx该指南面向 OAuth 场景引导用户在第三方平台注册自己的应用以获取 client id 与 secret--- title: How to register your own [Integration Name] OAuth app sidebarTitle: [Integration Name] Setup description: Register an OAuth app with [Integration Name] and connect it to Nango --- This guide shows you how to register your own app with [Integration Name] to obtain your OAuth credentials (client id secret). These are required to let your users grant your app access to their [Integration Name] account. Steps Step titleCreate a developer account Go to [Integration Name] Developer Portal and sign up for a developer account. /Step Step titleCreate a new application 1. Navigate to your applications/apps dashboard 2. Click Create New App or similar 3. Fill in the required details (app name, description) /Step Step titleConfigure OAuth settings 1. In your app settings, find OAuth or authentication settings 2. Add the Nango callback URL: https://api.nango.dev/oauth/callback 3. Select the scopes your application needs /Step Step titleGet your credentials Copy your **Client ID** and **Client Secret** from the app settings. Youll need these when configuring the integration in Nango. /Step Step titleNext Follow the _Quickstart_ to connect your first account. /Step /StepsOAuth2 是 Nango 集成中最常见的认证模式其回调地址统一为https://api.nango.dev/oauth/callback这是第三方平台 OAuth 流程重定向回 Nango 的固定终点。5.3 空 Syncs 片段Empty Syncs Snippet路径snippets/generated/[slug]/PreBuiltUseCases.mdx当某个集成还没有预构建同步/动作时用以下空状态占位这个文件永远要创建即使内容是空的_No pre-built syncs or actions available yet._ TipNot seeing the integration you need? Build your own independently./Tip六、两处配套配置更新6.1 docs.json注册导航在docs/docs.json的900 APIs Integrations分组中按字母序加入主页面路径实际仓库中的分组名见 docs/docs.json{ group: 900 APIs Integrations, pages: [ // ... other integrations alphabetically api-integrations/[slug], // ... more integrations ] }三条硬性规则只添加主页面路径绝不添加设置指南或连接指南——后者通过主页面内的链接访问不进入导航组内保持字母序提交前记得运行npm run docs:generate:llms重新生成llms.txt、llms-full.txt与api-catalog.txt生成器读取docs/docs.json、页面 frontmatter 与packages/providers/providers.yaml详见 docs/AGENTS.md。6.2 providers.yaml补充 provider 元数据在packages/providers/providers.yaml中新增或更新 provider 条目挂上文档 URL[slug]: display_name: [Integration Name] # ... other provider config ... docs: https://nango.dev/docs/api-integrations/[slug] setup_guide_url: https://nango.dev/docs/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app若存在连接指南还需追加docs_connect: https://nango.dev/docs/api-integrations/[slug]/connect七、认证类型变体模板并非一成不变需按认证类型调整设置指南认证类型设置指南标题差异点OAuth2最常见How to register your own [Name] OAuth app使用标准模板关联 OAuth 文档标注回调地址API KeyHow to obtain your [Name] API key聚焦在哪里查找/生成 API key无需 OAuth 回调Basic AuthHow to configure [Name] credentials记录用户名/密码或 API key 要求八、完整实例仓库中的 Slack 集成文档技能文档以 Slack 为完整示例而该示例在仓库中真实存在可直接对照阅读主页面docs/api-integrations/slack.mdx——frontmatter 标题为SlackQuickstart 第三步的示例端点正是 Slack 的conversations.list带limit10参数Node 示例通过nango.get({ endpoint: /conversations.list, params: { limit: 10 }, ... })调用Guides 区块除了注册 OAuth app 外还链接了 webhooks 指南 与 用户访问令牌指南。设置指南docs/api-integrations/slack/how-to-register-your-own-slack-api-oauth-app.mdx——包含 6 步加入 Slack Developer Program → 从零创建 Slack app → 配置 OAuth 重定向 URLhttps://api.nango.dev/oauth/callback与 Bot/User 两类 scope → 在 App Manifest 中开启 token rotation → 可选创建 Developer Sandbox → 进入 Quickstart。该页面还给出了settings.token_rotation_enabled: true的 YAML 片段并说明开启后 Nango 会自动刷新 bot token 与 user token。providers.yaml 条目packages/providers/providers.yaml#L22813-L22843——slack 条目完整呈现了技能中要求的字段slack: display_name: Slack categories: - popular - productivity auth_mode: OAUTH2 authorization_url: https://slack.com/oauth/v2/authorize scope_separator: , alternate_access_token_response_path: authed_user token_url: https://slack.com/api/oauth.v2.access disable_pkce: true token_response_metadata: - incoming_webhook.url - incoming_webhook.channel - incoming_webhook.channel_id - bot_user_id - team.id proxy: base_url: https://slack.com/api retry: after: - retry-after paginate: type: cursor cursor_path_in_response: response_metadata.next_cursor cursor_name_in_request: cursor limit_name_in_request: limit webhook_routing_script: slackWebhookRouting webhook_user_defined_secret: true docs: https://nango.dev/docs/api-integrations/slack setup_guide_url: https://nango.dev/docs/api-integrations/slack/how-to-register-your-own-slack-api-oauth-app从源码结构看docs与setup_guide_url正是技能要求的两个属性webhook_routing_script: slackWebhookRouting则揭示了 Slack 的 webhook 路由逻辑是以脚本形式挂载在 provider 配置上的。Webhook 路由印证——webhooks.mdx 详细说明了路由原理Slack Events API 以 HTTP POST 投递事件Nango 从事件负载中提取team_id部分事件形状回退到team.id来匹配连接这一匹配字段与 providers.yaml 中token_response_metadata里登记的team.id遥相呼应——授权时即自动捕获无需额外元数据。无法匹配时原始 Slack 负载会按原样转发不带 Nango 包装字段消费方需要同时兼容两种形状。九、实施清单Implementation Checklist每新增一个集成的文档按此清单逐项打勾收集集成信息名称、slug、认证类型、API URL 等创建主页面docs/api-integrations/[slug].mdx创建设置指南docs/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app.mdx创建哪怕为空同步片段snippets/generated/[slug]/PreBuiltUseCases.mdx按字母序把主页面加入docs/docs.json的集成分组在packages/providers/providers.yaml条目中添加docs与setup_guide_url验证所有链接可访问校验 MDX 语法合法十、常见错误速查错误修正把设置指南加进 docs.json只加主页面设置指南通过链接访问Guides 区块链接格式错误使用/api-integrations/[slug]/how-to-register-your-own-[slug]-api-oauth-app指南链接后缺少两个空格在闭合括号)后补两个空格否则换行渲染失效slug 格式错误使用小写加连字符如google-calendar不是googleCalendar忘记 PreBuiltUseCases 片段即使为空也一定要创建未更新 providers.yaml必须添加docs与setup_guide_url属性总结Nango 的集成文档体系是一套高度模式化、可校验、可自动生成索引的流水线主页面负责2 分钟上手的 Quickstart 与指南入口设置指南负责把用户导向第三方平台的凭据申请流程docs.json与providers.yaml负责导航与 provider 元数据而snippets/generated/负责预构建同步的展示。掌握本文描述的这套骨架与约定后你可以为任何一个新集成产出与仓库中 Slack 文档同等质量、可通过mintlify broken-links校验的完整文档集配合npm run docs:generate:llms重新生成 LLM 友好索引还能让这些页面同时被搜索引擎与 AI Agent 高效检索和引用。【免费下载链接】nangoBuild product integrations with AI.项目地址: https://gitcode.com/GitHub_Trending/na/nango创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
