从 OpenAPI 到文档页：Supabase 文档仓库 Management API Reference 的生成链路与渲染架构解析

从 OpenAPI 到文档页Supabase 文档仓库 Management API Reference 的生成链路与渲染架构解析【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase本文以 .agents/skills/ask-the-docs/reference/management-api-reference.md 为核心骨架结合 supabase 文档仓库apps/docs中的实际 Makefile、codegen 脚本与 React 渲染源码逐层拆解 SupabaseManagement API Reference/docs/reference/api/*是如何从线上 OpenAPI 规范一路生成到静态页面、Markdown 导出与 GraphQL 搜索数据的。读完本文你将理解这条「下载 → 打包 → 建导航 → 代码生成 → 渲染 → 导出」管线的每一步职责、关键技术取舍如为何放弃--dereferenced、为何保留自研渲染器以及如何新增 API 文档功能或调整现有管线。管线总览一份 OpenAPI 规范如何变成 Reference 页面Management API Reference 是 Supabase 文档站中体量最大、与真实后端绑定最紧的参考文档之一。它的目标是从api.supabase.com 上实时发布的 OpenAPI 规范出发持续生成并保持文档与线上 API 一致。整个链路在 apps/docs/spec/Makefile 与 apps/docs/features/docs/Reference.generated.script.ts 中落地全流程可用下图概括把图展开就是六个环环相扣的阶段文档作者提醒这些脚本与产物会随版本漂移动手前务必对照当前仓库的 apps/docs/spec/Makefile 与 apps/docs/features/docs/Reference.generated.script.ts 核实Download下载在apps/docs/spec/下执行make download.api.v1用curl把线上的 Management API OpenAPI 规范拉回仓库根落盘为api_v1_openapi.json/api_v2_openapi.json。Bundle打包make dereference.api.v1调用 Redocly CLIredocly/cli的bundle命令输出到transforms/api_v1_openapi_deparsed.json等文件。这里有一个值得注意的细节——Management API 刻意省略了--dereferenced参数原因是规范里存在循环$refAPIErrorObject.issues指向APIErrorObject自身Redocly 无法把它扁平化为合法 JSON$ref的展开被推迟到 codegen 阶段用带循环保护的自研逻辑完成。Nav sections生成导航分组sections/generateMgmtApiSections.cts扫描两个规范的 operations/tags产出站点左侧导航所需的common-api-sections.json。Codegen代码生成codegen:references:legacy即Reference.generated.script.ts将 v1 与 v2 合并、手工解析$ref写出api.latest.endpointsById.json、api.latest.sections.json、api.latest.flat.json、api.latest.bySlug.json落在features/docs/generated/下这些 JSON 属于构建产物仓库中默认不提交。Runtime运行时渲染/reference/api/[operation]路由由ApiReferencePage→SectionSwitch→ApiEndpointSection驱动——注意这是自定义 React 组件而非 MDX且每个 Endpoint 独占一个页面对应内部 issue DOCS-1268 的拆分方案。手写的介绍性 MDX 位于docs/ref/api/。AgentsAgent 消费导出generate-reference-markdown.ts把同一份数据导出为public/markdown/reference/api.md供 LLM Agent 检索引用。值得澄清的是历史上存在的 EJS 方案generator/api.tsApiTemplate.ts已不是当前生效路径分析代码或改需求时不要被它误导。阶段一拉取实时规范 ——make download.api.v1OpenAPI 规范的质量直接决定文档质量因此管线的第一步是以线上为准。看 apps/docs/spec/Makefile 的实际实现download.api.v1: curl -sS https://api.supabase.com/api/v1-json $(REPO_DIR)/api_v1_openapi.json curl -sS https://api.supabase.com/api/v2-json $(REPO_DIR)/api_v2_openapi.json几点补充说明Management API 被拆成v1 与 v2 两份规范分别对应不同的 URL 端点后续 codegen 会把两者按 path/component 合并成单一视图详见阶段四。同一份 Makefile 还包含其他产品的下载目标如download.storage.v1拉取 Storage 的api.json、download.tsdoc.v2拉取 JS SDK 系列 TypeDoc JSON、download.mcp-tools-permissions拉取 Management API 公开的 MCP 工具权限投影供访问控制章节使用等。Auth 的下载目标当前被注释掉采用手动流程维护说明各规范维护策略并不统一。下载产物位于仓库根目录的apps/docs/spec/下本文档描述以仓库实际情况为准。阶段二Redocly bundle —— 以及那条刻意缺失的--dereferenced下载完成后apps/docs/spec/Makefile 调用 Redocly CLI 打包规范dereference.api.v1: npx --packageredocly/cli redocly bundle -o $(REPO_DIR)/transforms/api_v1_openapi_deparsed.json $(REPO_DIR)/api_v1_openapi.json npx --packageredocly/cli redocly bundle -o $(REPO_DIR)/transforms/api_v2_openapi_deparsed.json $(REPO_DIR)/api_v2_openapi.jsonMakefile 中的注释给出了不传--dereferenced的精确理由NOTE: no --dereferenced here — api_v2_openapi.json has a circular ref (APIErrorObject.issues-APIErrorObject) that Redocly cant flatten to JSON. v1 uses the same approach for consistency.$refsare resolved manually inwriteApiReferenceSections.也就是v2 的APIErrorObject.issues引用了APIErrorObject自身形成环若用--dereferenced强行展开会无限递归、无法产出 JSON。为保证 v1 与 v2 行为一致两者统一采用只 bundle、不 dereference策略把$ref的解析留到 codegen 阶段、由仓库自带的循环安全解析器处理。与之对照同 Makefile 中 Auth、Storage、Analytics 的打包目标都正常使用了--dereferenced见dereference.auth.v1、dereference.storage.v0、dereference.analytics.v0这从侧面印证了 Management API 的环引用是其特有约束。Redocly 的角色边界对 Management API 而言Redocly 在整条链路中只扮演OpenAPI 工具链bundle/lint角色绝不是页面渲染器。仓库中实际可用的任务包括任务位置说明Bundle打包make dereference.api.v1及 auth/storage/analytics 的同类目标通过npx --packageredocly/cli redocly bundle调用Lint校验make validate.analytics.v0唯一一处redocly lint --extendsminimalManagement API 目前没有 lint 目标如果未来要给 Management API 增加更严格的校验方向是在 download/transform 环节加深 Redocly lint 规则而不是替换渲染器见下文保持自研渲染路径一节。阶段三从 operations 到导航树 ——generateMgmtApiSections.cts打包后的规范只是一张扁平的 path 大表还不足以支撑文档站的分组导航。中间产物common-api-sections.json由 apps/docs/spec/sections/generateMgmtApiSections.cts 生成对应 Makefile 目标generate.sections.api.v1generate.sections.api.v1: npx tsx $(REPO_DIR)/sections/generateMgmtApiSections.cts \ $(REPO_DIR)/transforms/api_v1_openapi_deparsed.json \ $(REPO_DIR)/transforms/api_v2_openapi_deparsed.json \ $(REPO_DIR)/common-api-sections.json阅读该脚本源码可以看到它实际做的事先把多份规范的paths用Object.assign合并后者覆盖前者的同名冲突然后遍历每个路由的每个 HTTP method依次执行过滤与归类逻辑跳过带x-internal标记的内部接口以tags[0]作为一级分类category名按出现顺序建立{ type: category, title: tag }分组对每个 operation 做 slug 合法性校验正则^[a-z0-9](?:-[a-z0-9])*$再把operationId通过slugToTitle转成可读标题如去掉v\d版本前缀、-转空格、首字母大写生成{ type: operation, id, slug }叶子节点。最终产出的common-api-sections.json既是 codegen 合并 v1/v2 后裁剪操作树只保留规范里真实存在的 operation的依据也决定了 Reference 页面的目录结构。阶段四codegen 合并 v1v2 并解析循环引用真正的汇合点是codegen:references:legacy脚本入口为 apps/docs/features/docs/Reference.generated.script.ts。它对 Management API 的职责集中在writeApiReferenceSections()函数内核心动作有三步。第一步合并 v1 与 v2 规范。以 v1 为基底把 v2 的paths、components.schemas、components.securitySchemes展开合并进来const mergedSpec { ...apiV1Spec, paths: { ...apiV1Spec.paths, ...apiV2Spec.paths, }, components: { ...apiV1Spec.components, schemas: { ...apiV1Spec.components?.schemas, ...apiV2Spec.components?.schemas }, securitySchemes: { ...apiV1Spec.components?.securitySchemes, ...apiV2Spec.components?.securitySchemes }, }, }第二步手工解析$ref循环安全。脚本注释明确写了两点Management API 规范是未加--dereferenced打包的v2 在APIErrorObject.issues处存在循环引用因此要在这里手工resolveRefs遇到环时保留一条未展开的$ref指针而不是无限展开。实现上是经典的带refChain参数的递归if (refChain.includes(refPath)) { return { $ref: refPath } // 环不再展开保留指针 } if (!refPath.startsWith(#/)) return node // 只处理本地 #/components 引用这正对应原文档强调的cycle guard——它解决的是 Redocly--dereferenced无法解决的同一类问题只是把复杂度从工具层搬到了 codegen 层。第三步切片出多种视图并落盘。mapEndpointsById遍历合并后的spec.paths把每个 method 折叠成带{ id: operationId, path, method }的IApiEndPoint结构再由genApiSectionTreedeepFilterRec递归裁剪common-api-sections.json仅保留endpointsById中真实存在的 operation产出最终的四个 JSON 产物产物内容api.latest.endpointsById.jsonoperationId → EndPoint 明细的键值数组api.latest.sections.json带分类的完整导航/内容树api.latest.flat.json拍平后的 section 列表api.latest.bySlug.json按 slug 索引的字典供路由快速查找这组api.latest.*.json之所以取名 latest是因为它与 CDN/发布侧的最新版本一一对应运行时与导出共享同一份数据源。阶段五运行时渲染 —— 为什么坚持自定义 React 组件页面渲染阶段Management API 走的是自定义 React 渲染路径而不是嵌入 Scalar、Redoc 或 Stoplight Elements 这类第三方 OpenAPI UI 套件。技术栈为ApiReferencePage→SectionSwitch→ApiEndpointSection相关实现位于 apps/docs/features/docs/Reference.apiPage.tsx 与 apps/docs/features/docs/Reference.sections.tsxschema 显示辅助逻辑在 apps/docs/features/docs/Reference.api.utils.tsIApiEndPoint类型即定义于此。保留自研路径的理由原文档归纳为四条这里结合源码逐条解读两条管线共享同一数据结构。HTML 页面渲染、Markdown 导出给 Agent 用、GraphQL 文档搜索三者共用一个IApiEndPoint/ 生成的 JSON 结构。引入第三方查看器必然 fork 这份数据模型导致双份维护。事实上 apps/docs/internals/generate-reference-markdown.ts 的renderApi()就是直接读取api.latest.sections.jsonapi.latest.endpointsById.json来产出public/markdown/reference/api.md的——两套出口、一份数据正是这种共享数据、共享代码路径之外的一切的设计。自定义扩展字段需要一等公民渲染。Management API 规范带有一批x-前缀扩展如x-oauth-scopeOAuth 作用域、x-allowed-plans允许的套餐、x-fga-permissions基于 FGA 的权限模型。这些信息需要专门的 UI 呈现通用查看器不会为你渲染它们。在源码中搜索即可发现这些字段贯穿于 Reference 的工具函数与导航代码中。模块化页面方向不容倒退。DOCS-1268 已经把原先巨大的单体 API 页拆成一 operation 一页大幅提升加载与可维护性嵌入整本规范的可视化查看器等于把单体化又请回来。维护面积与产品方向约束。新增依赖、主题适配、与既有站点功能对齐都要付出成本与文档站减小表面积、不增加平行渲染器的方向相悖。因此原文档给出的行动建议非常明确想改进就用好现有轮子——优先增强ApiEndpointSection或 schema 辅助组件或在 download/transform 环节加深 Redocly lint 规则除非能同时解决 Markdown 导出、搜索与x-*字段的一致性否则不要提出用 OpenAPI UI 套件替换渲染器。如果 Redocly 不可用时的备选原文档顺带给出了工具链兜底方案bundle 环节可用apidevtools/swagger-parser或swagger-cli替代 Redoclylint 环节可用 Spectral 替代但作者冷静评价——在自研的循环安全解析器仍被需要的前提下这类替换收益甚微。这也说明真正不可替代的资产是仓库自带的解析与渲染代码而非某个具体 CLI。阶段六给 Agent 的 Markdown 导出为了让 LLM / Agent 能在文档检索ask-the-docs等场景直接消费 Management API Referencedocs 仓库把 codegen 产物二次渲染为纯 Markdown。生成器位于 apps/docs/internals/generate-reference-markdown.ts输出为public/markdown/reference/api.md。其renderApi()逻辑与页面端同源遍历sections对type: category输出##标题对type: markdown的条目读取docs/ref/api/下的手写.mdx并用stripMdxJsx去掉 JSX 标签、还原纯文本外部再经 GFM 的 mdast 往返并统一加 base URL 前缀对type: operation的条目则以 operation 的summary为标题、渲染METHOD path、描述与参数清单name/ 类型 / 是否必填。最终每个 API 端点以标题 请求行 说明 参数列表的规整结构呈现天然适合检索与引用。这套产物与build:markdownguides reference 一键生成、docs.tar.gz归档共同构成了 Agent 友好的静态面其消费方式详见.agents/skills/ask-the-docs/reference/llm-agent-surface.md。附加环节Personal Access TokenPAT作用域权限表Management API Reference 体系下还有一块独立于上面六步的生成式文档Personal Access Tokens 指南中的权限表与 MCP 工具表。原文档指出这些表格并非手写而是由三路输入实时生成Management API 规范v1/v2 的transforms/*_deparsed.jsonMCP 工具权限映射mcp_tools_permissions.json由make download.mcp-tools-permissions拉取Studio 与 docs 共享的同一份权限目录。重新生成命令为make -C apps/docs/spec generate.partials.access-control对应 apps/docs/spec/sections/generateAccessControlPartials.mts它会覆写 apps/docs/content/_partials/access-control/scoped_pat_permissions.mdx 与scoped_pat_mcp_tools.mdx生成后再用 Prettier 统一格式。质量保障机制是双重的Docs Tests 会在相关 PR 上运行它partials 一旦与规范漂移即构建失败此外 Management API 的周更流程在刷新线上输入后也会重跑该目标。这意味着权限文档永远不会与后端实际强制规则脱节。关键文件速查表对想要深入阅读或参与贡献的人来说记住下面这张地图最有价值路径角色apps/docs/spec/Makefile规范下载 / Redocly bundle / section 生成 / PAT partials 生成的统一入口apps/docs/spec/sections/generateMgmtApiSections.ctsOpenAPI paths tags →common-api-sections.json导航树apps/docs/features/docs/Reference.generated.script.ts合并 v1v2、循环安全地解析$ref、写出api.latest.*JSONapps/docs/features/docs/Reference.api.utils.tsIApiEndPoint类型与 schema 显示辅助apps/docs/features/docs/Reference.apiPage.tsx路由 → 单 operation 页面apps/docs/features/docs/Reference.sections.tsxApiEndpointSection等渲染组件apps/docs/internals/generate-reference-markdown.tsAgent 版 Markdown 导出api.md原文档还挂接了三个相邻主题便于你在仓库中继续延伸阅读以下均从仓库根目录出发.agents/skills/ask-the-docs/reference/build-pipeline.md —codegen:references在 docs 预构建prebuild中与 GraphQL codegen、example 拷贝、Markdown 导出、gz 归档的编排关系.agents/skills/ask-the-docs/reference/app-map.md — Reference 与 Guides 的路由/目录分工.agents/skills/ask-the-docs/reference/known-issues.md — Reference 页刻意规避标准 MDX、长度与模块化方向的背景.agents/skills/ask-the-docs/reference/llm-agent-surface.md — Markdown 导出的消费端。结语一条为可持续一致而设计的管线纵观整条链路Management API Reference 的架构风格非常统一下载、打包、导航生成、codegen、渲染、导出六个阶段各司其职且刻意让数据与呈现解耦。它不引入重量级 OpenAPI UI 全家桶而是用自研 React 组件 循环安全的$ref解析器换取对x-*扩展字段、GraphQL 搜索和 Markdown 导出的完全掌控它把规范漂移的风险用周更 CI 校验 自动生成 partials三道闸门压到最低。对任何想维护一套API 即文档、文档即代码体系的工程团队而言这份参考资料的取舍理由与 Makefile/codegen 实现本身就是一份可复用的最佳实践样本。【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考