【免费下载链接】forge项目地址https://gitcode.com/gh_mirrors/forge55/forge点击查看免费下载forge是 Cloudflare 开源的 schema-first OpenAPI 工具框架其中的astro-fern负责把 OpenAPI 规范转换成可直接部署的 API 文档站。本指南面向新手和普通用户带你完整走一遍如何用Astro astro-fern从零搭建一个OpenAPI 驱动的 API 文档站涵盖目录结构、核心配置、路由策略、AI Agent 友好输出llms.txt以及部署注意事项。 先搞清楚三个角色各管什么理解分工是入门第一步数据归astro-fern展示归你的 Astro 应用。角色负责内容astro-fernOpenAPI 加载、快照、代码示例snippets、目录catalog、路由规划、Agent 文档fern-forge通过扩展 API 校验 Forge 元数据、提供 SDK 投影你的 Astro 应用HTML、导航、主题、代码渲染器、可见性策略、自定义 URL 一句话记忆astro-fern提供归一化的内容和懒加载服务端 API你的应用只负责把它画出来。 快速上手最小可用的 5 个核心文件一个能跑起来的 astro-fern 文档站只需要 5 个文件文件作用astro.config.mjs注册集成、适配器、路由策略、Agent 选项src/content.config.ts注册apiReference目录提供内容策略src/live.config.ts注册apiOperations实时集合src/env.d.ts为Astro.locals补充类型src/pages/api/[...slug].astro在配置的 Fern base 下渲染人类操作页面⚠️ 集合名apiReference与apiOperations是固定的因为服务端 API 靠它们定位目录和操作工件。1️⃣ 配置 Astro在astro.config.mjs中引入astroFern集成示例使用 Node 适配器// astro.config.mjs import node from astrojs/node; import astroFern from astro-fern; import { defineConfig } from astro/config; export default defineConfig({ output: server, adapter: node({ mode: standalone }), integrations: [ astroFern({ routing: { base: /api, target: path }, }), ], });生产环境请把SITE_URL设为公开部署源本地开发时集成会通过Astro.locals自动提供一个 artifact fetcher。2️⃣ 注册内容content.config在src/content.config.ts里声明产品products、目标targets和 OpenAPI 源// src/content.config.ts import { defineFernManifest, type FernContentOptions } from astro-fern; import { defineFernCollections } from astro-fern/collections; const manifest defineFernManifest({ targets: [{ id: curl, kind: http, label: curl, language: bash }], products: [ { id: dns, pathPrefixes: [/zones], sections: [{ id: records, tag: DNS Records, title: DNS records }], }, ], }); export const collections { ...defineFernCollections({ source: new URL(./openapi.json, import.meta.url), manifest, } satisfies FernContentOptions), };把带DNS Records标签的接口放进src/openapi.json/zones下的操作就自动归到dns产品。3️⃣ 注册操作加载器live.config// src/live.config.ts import { defineLiveCollection } from astro:content; import { fernOperationLiveLoader } from astro-fern/live; export const collections { apiOperations: defineLiveCollection({ loader: fernOperationLiveLoader(), }), };4️⃣ 补充本地类型// src/env.d.ts /// reference typesastro/client / /// reference typesastro-fern/locals /5️⃣ 渲染一个操作页--- // src/pages/api/[...slug].astro import { getFernPageForPath } from astro-fern/server; export const prerender false; const fetcher Astro.locals.fernArtifactFetcher; const resolved await getFernPageForPath(Astro.url.pathname, { ...(fetcher ? { request: Astro.request, fetcher } : {}), }); if (!resolved) return new Response(Not found, { status: 404 }); const { page, target } resolved; --- main h1{page.operation.title}/h1 p{page.operation.httpMethod} {page.operation.path}/p div set:html{page.operation.description.html} / /main 关键坑astro.config 与 content.config 的分工新手最容易踩的坑是——这两个文件运行在不同的模块图里职责不能混运行时路由选项routing、agents→ 写在astro.configOpenAPI 源和内容策略source、manifest、snippets→ 写在content.config真实的 Cloudflare 文档站就是把两者彻底分开维护的可直接对照 packages/docs-site/astro.config.mjs 与 packages/docs-site/src/content.config.ts。️ 定义产品与区段ManifestManifest 为导航和路由提供稳定身份核心是targetsproductsconst manifest defineFernManifest({ targets: [curlTarget], products: [ { id: dns, title: DNS, description: Manage DNS records and settings., sdkGroup: dns, pathPrefixes: [/zones], sections: [ { id: records, tag: DNS Records, title: Records }, { id: settings, tag: DNS Settings, title: Settings }, ], }, ], });产品归属规则按优先级带sdkGroup的产品接收第一段 SDK 组相等的操作优先于pathPrefixes。不带sdkGroup但有pathPrefixes的产品用路径前缀匹配。两者都没有的产品可接收属于其任一 section 的操作。当任意 OpenAPI tag精确匹配section 的tag时该 section 接收这个操作。一个操作可属于多个产品当且仅当所有匹配产品都声明了sdkGroup。 不想手写产品discoverProducts()能从 SDK 组首段推导产品 ID、从每个操作的首个 tag 推导 section一步到位。 路由策略hash 还是 path模式路径示例适用场景Hash默认/api/dns/records/methods/list/#curltarget 是交互式状态一份文档服务所有 targetPath/api/dns/curl/records/methods/list/每个 target 都需要独立可索引的文档利于 SEO非默认快照会在产品后插入 slug例如/api/dns/records/methods/list/ /api/dns/v1/records/methods/list/ 选择建议每个 target 都要被搜索引擎独立收录 → 用pathtarget 只是页内切换 → 用hash。 面向 AI AgentMarkdown 与 llms.txtastro-fern 默认会注入纯 Markdown 操作文档和嵌套的llms.txt索引让 LLM / AI 助手能高效读取你的 API 文档选项默认作用agents.injectRoutestrue挂载配置的 agent 路由agents.markdowntrue为每个操作规划聚合 每 target 的 Markdownagents.llms全部作用域规划 site / product / snapshot / target 索引agents.directive默认指令前置说明文字设为false可省略llms.txt各级作用域路径作用域路径内容site/llms.txt所有产品product/api/{product}/llms.txt默认快照中的产品snapshot/api/{product}/{slug}/llms.txt一个产品快照target/api/{product}/targets/{target}/llms.txt一个 target 的操作 想在应用里自己控制挂载路径把agents.injectRoutes设为false用getAgentRoutes()拿到所需路径即可。 版本快照Snapshots一个 snapshot 代表一个被文档化的 API 状态。单一 source 会创建一个隐式快照id/slugcurrentdefault: true。需要多版本时显式声明source: { kind: snapshots, snapshots: [ { id: v1, label: Version 1, slug: v1, source: new URL(./openapi.v1.json, import.meta.url) }, { id: v2, label: Version 2, slug: v2, default: true, source: new URL(./openapi.v2.json, import.meta.url) }, ], },每个快照有自己的 source、身份、label、slug、default标志和可选 target 覆盖。跨版本切换时直接用内置的无样式组件--- import SnapshotSwitcher from astro-fern/components/SnapshotSwitcher.astro; --- SnapshotSwitcher labelAPI version /它会在至少有一个可用快照时渲染锚点链接没有适用快照时不渲染任何标记。 部署要点别漏了内容加载会把目录写入public/_astro-fern/operations/与catalogs/保留该路径并纳入部署静态资源。用.gitignore忽略public/_astro-fern/。以 digest 命名的文件给一个长且不可变的缓存如Cache-Control: public, max-age31536000, immutable。把site设为可信公开源或向页面加载辅助函数传origin。⚠️不要把密钥放进 OpenAPI 字段、扩展数据或 snippet 渲染器输出——操作工件是公开可访问的。️ 本地运行参考# 克隆仓库并安装依赖 git clone https://gitcode.com/gh_mirrors/forge55/forge cd forge pnpm install # 类型检查 / Lint / 单元测试 pnpm typecheck pnpm check pnpm test # 开发 / 构建文档站 pnpm --filter docs-site dev pnpm --filter docs-site build 延伸阅读与关键源码完整官方文档packages/astro-fern/README.md集成入口packages/astro-fern/integration.tsManifest 定义packages/astro-fern/manifest.ts内容集合packages/astro-fern/collections.ts实时加载器packages/astro-fern/operation-live-loader.ts服务端 APIpackages/astro-fern/server.ts真实文档站配置packages/docs-site/astro.config.mjs内容注册packages/docs-site/src/content.config.ts实时集合packages/docs-site/src/live.config.ts操作渲染页packages/docs-site/src/pages/[product]/[...slug].astroForge 扩展packages/fern-forge/README.md文档站说明packages/docs-site/README.md赞分享【免费下载链接】forge项目地址https://gitcode.com/gh_mirrors/forge55/forge点击查看免费下载相关推荐在 Astro 站点中集成 Scalar API Reference基于 OpenAPI/Swagger 的完整配置指南在 Astro 站点中集成 Scalar API Reference基于 OpenAPI/Swagger 的完整配置指南 本篇技术指南讲解如何在 Astro开发工具API 工具前端Starlight基于Astro构建现代化文档网站框架Starlight基于Astro构建现代化文档网站框架 Starlight是一个基于Astro框架构建的全功能文档网站框架专为现代化技术文档需求而设计。它结文档前端开发工具Docker Curriculum 的 Starlight 文档站基于 Astro 的 Docker 教程站点构建与定制指南Docker Curriculum 的 Starlight 文档站基于 Astro 的 Docker 教程站点构建与定制指南 导读 本文围绕开源仓库 dock云原生DevOps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考