在 Astro Starlight 文档站中集成 Scalar API Referencescalar/starlight 插件完整上手指南【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本文围绕scalar/starlight插件的快速上手展开它能把 Scalar 渲染的 API Reference 以插件注入的路由形式嵌入 Astro Starlight 文档站让你在普通 Markdown 文档页旁边直接获得一份独立维护、可交互的 API 文档。读完本文你将掌握插件的安装方式、最小配置、configuration/pathname/label/title四个核心选项、多 API Reference 的部署方法以及插件在路由注入与侧边栏处理上的底层实现原理。从文档页到 API Reference这个插件解决什么问题在 Starlight 文档站中内容页存放在src/content/docs/目录下并自动出现在侧边栏中。例如 getting-started.md 中描述的场景这是一个普通的 Starlight 文档页位于src/content/docs/guides/目录会以Guides分组出现在侧边栏侧边栏中紧随其下的API Reference条目并不是一个真实的文件而是由scalar/starlight插件添加的该插件同时负责在/api-reference路径提供 API Reference 页面。也就是说你不需要手工创建页面、复制粘贴ScalarComponent组件并维护路由——安装插件、传入一个 OpenAPI 文档地址剩下的交给插件完成。这与scalar/astro等集成方式相比最大的差别是渲染结果会被包裹在 Starlight 的布局中保留文档站原有的站点头部和侧边栏视觉与导航体验完全一致。安装与最小配置在 Astro Starlight 项目中安装插件npm install scalar/starlight然后在astro.config.mjs中把插件挂到 Starlight 的plugins数组里并指向你的 OpenAPI 文档// astro.config.mjs import { defineConfig } from astro/config import starlight from astrojs/starlight import { scalarStarlight } from scalar/starlight export default defineConfig({ integrations: [ starlight({ title: My Docs, plugins: [ scalarStarlight({ // Scalar 的通用配置对象url 指向 OpenAPI 文档 configuration: { url: /openapi.json, }, }), ], }), ], })最小配置只需要一个configuration.url。默认情况下API Reference 会从/api-reference路径提供。仓库中的 playground 实际配置与此一致见 astro.config.mjs它把url指向了https://registry.scalar.com/scalar/apis/galaxy?formatjson这份示例 OpenAPI 文档。验证效果文档站里“试一试”按照 getting-started.md 中的指引启动开发服务器后可以做两件事来验证集成是否成功从侧边栏点击API Reference入口浏览器会打开/api-reference路径看到渲染完成的 Scalar API Reference包含操作列表、请求示例、Schema 等交互能力编辑任意文档页例如src/content/docs/guides/下的 Markdown 文件保存后页面会热更新——普通文档内容与 API Reference 在同一套侧边栏结构下并存互不干扰。这个“编辑即更新”的行为来自 Starlight 的开发服务器热更新机制而 API Reference 页面本身则依赖 Starlight 的客户端路由详见下文实现原理一节。完整配置项插件接收一个选项对象类型定义在 plugin.ts 中共四个字段选项默认值说明configuration—必填Scalar 的通用配置对象最重要的是urlOpenAPI 文档地址或content内联的 OpenAPI 内容其余字段与 Scalar API Reference 的全局配置一致pathname/api-referenceAPI Reference 页面提供服务的路径labelAPI Reference侧边栏条目的显示文本title取label的值API Reference 页面的title标题注意一个约束configuration会被序列化为 JSON 写入页面因此函数类型的选项自定义fetch、onLoaded回调、Scalar 插件等不会生效——这与scalar/astro的renderModeclient行为一致因为本插件正是基于它构建的见 README.md。pathname需要以单个正斜杠开头且不能以正斜杠结尾。它先经过normalizePathname归一化处理见 normalize-pathname.ts拆分并过滤空段后重新拼接因此reference/、//docs//api/这类写法会被统一规整为/reference、/docs/api。若归一化后解析为/即站点根路径插件会直接抛出错误提示你改用/api-reference之类的子路径避免与首页路由冲突。自定义路由与侧边栏文本guides/customize.md 给出了一个实用的自定义示例——更换服务路径并重命名侧边栏条目// astro.config.mjs scalarStarlight({ configuration: { url: /openapi.json }, pathname: /reference, label: API, })效果API Reference 不再位于/api-reference而是/reference侧边栏条目由 “API Reference” 变为 “API”页面标题默认跟随label即 “API”除非你显式传入title覆盖。当传入pathname: reference/时测试用例见 plugin.test.ts会验证侧边栏链接被归一化为/reference且自定义的title与归一化后的pathname被正确转发给路由集成。pathname既作为 Astro 路由模式又作为 Starlight 侧边栏链接因此两处必须使用同一套归一化逻辑这正是normalizePathname被独立成模块、由插件与路由组件共用同一个文件的原因。侧边栏的两种处理策略插件在config:setup钩子中处理侧边栏见 plugin.ts行为取决于你的 Starlight 配置你显式定义了sidebar插件会保留现有条目并在末尾追加{ label, link: pathname }例如已有的Guides分组之后多出 “API Reference” 入口。对应测试用例keeps existing sidebar entries验证了这一点你没有定义sidebarStarlight 会基于src/content/docs/自动生成侧边栏。此时插件不会追加条目——如果强行追加会把自动生成的侧边栏替换成只有一项的显式配置从而隐藏你的其他所有页面。插件只会打印一条 warn 日志提示你手动添加链接例如sidebar: [{ label: API Reference, link: /api-reference }]这正是 playground 中 astro.config.mjs 显式声明sidebar: [{ label: Guides, autogenerate: { directory: guides } }]的原因显式侧边栏让插件可以安全地在其后追加 API Reference 入口。多 API Reference一个站点多份接口文档如果产品有多个服务可以在plugins数组中多次调用scalarStarlight每次指定独立的pathnameplugins: [ scalarStarlight({ pathname: /reference/payments, label: Payments, configuration: { url: /payments.json } }), scalarStarlight({ pathname: /reference/billing, label: Billing, configuration: { url: /billing.json } }), ]这样/reference/payments与/reference/billing会各自渲染一份 API Reference侧边栏出现 “Payments” 与 “Billing” 两个入口。底层实现上所有插件的实例会把各自的引用注册进一个以pathname为键的模块级注册表见 integration.ts由一个打包好的.astro组件在渲染时根据当前请求路径挑选对应的引用。需要注意两个不同的引用共用同一个pathname会抛出错误“Two different API references are configured for …”要求为每个引用分配独立路径重复注册完全相同的引用则被允许这兼容了开发服务器配置重载的场景每个注入的 Astro 集成按scalar/starlight:${pathname}命名避免 Astro 把多个集成误判为同一个而只保留第一个。底层实现原理路由注入、虚拟模块与客户端渲染scalar/starlight的运作链路可以分为三层均位于 src 目录下Starlight 插件层plugin.ts在config:setup钩子中做两件事——通过addIntegration注入路由集成、通过updateConfig追加侧边栏条目。由于 Starlight 插件本身无法直接注入路由注入动作被委托给一个 Astro 集成完成。Astro 集成层integration.ts在astro:config:setup钩子中调用injectRoute把pathname模式指向包内自带的ScalarReference.astro组件同时注册一个 Vite 虚拟模块插件把注册表中的所有引用标题 配置序列化导出为virtual:scalar-starlight模块。因为注入的路由组件是打包产物、无法接收按实例区分的 props所以通过虚拟模块在构建期传递数据是标准做法。渲染组件层ScalarReference.astro从虚拟模块读取references注册表剥离BASE_URL后用与插件相同的normalizePathname匹配出当前请求对应的引用匹配失败时若只有一个引用则回退到它若有多个引用则直接抛错避免静默渲染错误文档。随后用StarlightPage包裹ScalarComponent renderModeclient configuration{configuration} /并采用template: splash让 API Reference 获得整行内容宽度Scalar 自带操作侧边栏。renderModeclient是这里的关键约束Starlight 自带ClientRouter /导航在客户端进行若采用静态渲染脚本切页后脚本只会等到手动刷新才执行。客户端渲染模式保证了跨 Starlight 客户端导航时 API Reference 依然正常工作。测试用例行为如何被验证仓库为插件编写了完整的 Vitest 测试见 plugin.test.ts覆盖了以下核心行为可作为你配置时的行为契约插件名为scalar/starlight且提供config:setup钩子默认追加{ label: API Reference, link: /api-reference }侧边栏条目已有侧边栏条目会被保留新条目追加在末尾自定义pathname/label/title被正确归一化并转发注入的集成按pathname命名页面标题默认取labelpathname归一化为/时抛出错误包括/与///两种写法未配置sidebar时不修改配置、只记录一条 warn 日志//docs//api/这类杂乱路径被归一化为/docs/api。在仓库中本地体验若想直接体验可以查看本仓库中的 integrations/starlight/playground 目录它是一套完整的 Astro Starlight 演示站包含astro.config.mjs、src/content.config.ts以及src/content/docs/下的文档页index.mdx、guides/getting-started.md、guides/customize.md。对照 getting-started.md 与 customize.md 两篇示例文档可以直观看到“普通文档页 插件注入的 API Reference”在真实项目中的组织方式。完整选项列表与注意事项以 integrations/starlight/README.md 为准插件的类型定义与实现细节可进一步阅读 plugin.ts、integration.ts 与 normalize-pathname.ts。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Astro Starlight 文档站中集成 Scalar API Reference：@scalar/starlight 插件完整上手指南
在 Astro Starlight 文档站中集成 Scalar API Referencescalar/starlight 插件完整上手指南【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本文围绕scalar/starlight插件的快速上手展开它能把 Scalar 渲染的 API Reference 以插件注入的路由形式嵌入 Astro Starlight 文档站让你在普通 Markdown 文档页旁边直接获得一份独立维护、可交互的 API 文档。读完本文你将掌握插件的安装方式、最小配置、configuration/pathname/label/title四个核心选项、多 API Reference 的部署方法以及插件在路由注入与侧边栏处理上的底层实现原理。从文档页到 API Reference这个插件解决什么问题在 Starlight 文档站中内容页存放在src/content/docs/目录下并自动出现在侧边栏中。例如 getting-started.md 中描述的场景这是一个普通的 Starlight 文档页位于src/content/docs/guides/目录会以Guides分组出现在侧边栏侧边栏中紧随其下的API Reference条目并不是一个真实的文件而是由scalar/starlight插件添加的该插件同时负责在/api-reference路径提供 API Reference 页面。也就是说你不需要手工创建页面、复制粘贴ScalarComponent组件并维护路由——安装插件、传入一个 OpenAPI 文档地址剩下的交给插件完成。这与scalar/astro等集成方式相比最大的差别是渲染结果会被包裹在 Starlight 的布局中保留文档站原有的站点头部和侧边栏视觉与导航体验完全一致。安装与最小配置在 Astro Starlight 项目中安装插件npm install scalar/starlight然后在astro.config.mjs中把插件挂到 Starlight 的plugins数组里并指向你的 OpenAPI 文档// astro.config.mjs import { defineConfig } from astro/config import starlight from astrojs/starlight import { scalarStarlight } from scalar/starlight export default defineConfig({ integrations: [ starlight({ title: My Docs, plugins: [ scalarStarlight({ // Scalar 的通用配置对象url 指向 OpenAPI 文档 configuration: { url: /openapi.json, }, }), ], }), ], })最小配置只需要一个configuration.url。默认情况下API Reference 会从/api-reference路径提供。仓库中的 playground 实际配置与此一致见 astro.config.mjs它把url指向了https://registry.scalar.com/scalar/apis/galaxy?formatjson这份示例 OpenAPI 文档。验证效果文档站里“试一试”按照 getting-started.md 中的指引启动开发服务器后可以做两件事来验证集成是否成功从侧边栏点击API Reference入口浏览器会打开/api-reference路径看到渲染完成的 Scalar API Reference包含操作列表、请求示例、Schema 等交互能力编辑任意文档页例如src/content/docs/guides/下的 Markdown 文件保存后页面会热更新——普通文档内容与 API Reference 在同一套侧边栏结构下并存互不干扰。这个“编辑即更新”的行为来自 Starlight 的开发服务器热更新机制而 API Reference 页面本身则依赖 Starlight 的客户端路由详见下文实现原理一节。完整配置项插件接收一个选项对象类型定义在 plugin.ts 中共四个字段选项默认值说明configuration—必填Scalar 的通用配置对象最重要的是urlOpenAPI 文档地址或content内联的 OpenAPI 内容其余字段与 Scalar API Reference 的全局配置一致pathname/api-referenceAPI Reference 页面提供服务的路径labelAPI Reference侧边栏条目的显示文本title取label的值API Reference 页面的title标题注意一个约束configuration会被序列化为 JSON 写入页面因此函数类型的选项自定义fetch、onLoaded回调、Scalar 插件等不会生效——这与scalar/astro的renderModeclient行为一致因为本插件正是基于它构建的见 README.md。pathname需要以单个正斜杠开头且不能以正斜杠结尾。它先经过normalizePathname归一化处理见 normalize-pathname.ts拆分并过滤空段后重新拼接因此reference/、//docs//api/这类写法会被统一规整为/reference、/docs/api。若归一化后解析为/即站点根路径插件会直接抛出错误提示你改用/api-reference之类的子路径避免与首页路由冲突。自定义路由与侧边栏文本guides/customize.md 给出了一个实用的自定义示例——更换服务路径并重命名侧边栏条目// astro.config.mjs scalarStarlight({ configuration: { url: /openapi.json }, pathname: /reference, label: API, })效果API Reference 不再位于/api-reference而是/reference侧边栏条目由 “API Reference” 变为 “API”页面标题默认跟随label即 “API”除非你显式传入title覆盖。当传入pathname: reference/时测试用例见 plugin.test.ts会验证侧边栏链接被归一化为/reference且自定义的title与归一化后的pathname被正确转发给路由集成。pathname既作为 Astro 路由模式又作为 Starlight 侧边栏链接因此两处必须使用同一套归一化逻辑这正是normalizePathname被独立成模块、由插件与路由组件共用同一个文件的原因。侧边栏的两种处理策略插件在config:setup钩子中处理侧边栏见 plugin.ts行为取决于你的 Starlight 配置你显式定义了sidebar插件会保留现有条目并在末尾追加{ label, link: pathname }例如已有的Guides分组之后多出 “API Reference” 入口。对应测试用例keeps existing sidebar entries验证了这一点你没有定义sidebarStarlight 会基于src/content/docs/自动生成侧边栏。此时插件不会追加条目——如果强行追加会把自动生成的侧边栏替换成只有一项的显式配置从而隐藏你的其他所有页面。插件只会打印一条 warn 日志提示你手动添加链接例如sidebar: [{ label: API Reference, link: /api-reference }]这正是 playground 中 astro.config.mjs 显式声明sidebar: [{ label: Guides, autogenerate: { directory: guides } }]的原因显式侧边栏让插件可以安全地在其后追加 API Reference 入口。多 API Reference一个站点多份接口文档如果产品有多个服务可以在plugins数组中多次调用scalarStarlight每次指定独立的pathnameplugins: [ scalarStarlight({ pathname: /reference/payments, label: Payments, configuration: { url: /payments.json } }), scalarStarlight({ pathname: /reference/billing, label: Billing, configuration: { url: /billing.json } }), ]这样/reference/payments与/reference/billing会各自渲染一份 API Reference侧边栏出现 “Payments” 与 “Billing” 两个入口。底层实现上所有插件的实例会把各自的引用注册进一个以pathname为键的模块级注册表见 integration.ts由一个打包好的.astro组件在渲染时根据当前请求路径挑选对应的引用。需要注意两个不同的引用共用同一个pathname会抛出错误“Two different API references are configured for …”要求为每个引用分配独立路径重复注册完全相同的引用则被允许这兼容了开发服务器配置重载的场景每个注入的 Astro 集成按scalar/starlight:${pathname}命名避免 Astro 把多个集成误判为同一个而只保留第一个。底层实现原理路由注入、虚拟模块与客户端渲染scalar/starlight的运作链路可以分为三层均位于 src 目录下Starlight 插件层plugin.ts在config:setup钩子中做两件事——通过addIntegration注入路由集成、通过updateConfig追加侧边栏条目。由于 Starlight 插件本身无法直接注入路由注入动作被委托给一个 Astro 集成完成。Astro 集成层integration.ts在astro:config:setup钩子中调用injectRoute把pathname模式指向包内自带的ScalarReference.astro组件同时注册一个 Vite 虚拟模块插件把注册表中的所有引用标题 配置序列化导出为virtual:scalar-starlight模块。因为注入的路由组件是打包产物、无法接收按实例区分的 props所以通过虚拟模块在构建期传递数据是标准做法。渲染组件层ScalarReference.astro从虚拟模块读取references注册表剥离BASE_URL后用与插件相同的normalizePathname匹配出当前请求对应的引用匹配失败时若只有一个引用则回退到它若有多个引用则直接抛错避免静默渲染错误文档。随后用StarlightPage包裹ScalarComponent renderModeclient configuration{configuration} /并采用template: splash让 API Reference 获得整行内容宽度Scalar 自带操作侧边栏。renderModeclient是这里的关键约束Starlight 自带ClientRouter /导航在客户端进行若采用静态渲染脚本切页后脚本只会等到手动刷新才执行。客户端渲染模式保证了跨 Starlight 客户端导航时 API Reference 依然正常工作。测试用例行为如何被验证仓库为插件编写了完整的 Vitest 测试见 plugin.test.ts覆盖了以下核心行为可作为你配置时的行为契约插件名为scalar/starlight且提供config:setup钩子默认追加{ label: API Reference, link: /api-reference }侧边栏条目已有侧边栏条目会被保留新条目追加在末尾自定义pathname/label/title被正确归一化并转发注入的集成按pathname命名页面标题默认取labelpathname归一化为/时抛出错误包括/与///两种写法未配置sidebar时不修改配置、只记录一条 warn 日志//docs//api/这类杂乱路径被归一化为/docs/api。在仓库中本地体验若想直接体验可以查看本仓库中的 integrations/starlight/playground 目录它是一套完整的 Astro Starlight 演示站包含astro.config.mjs、src/content.config.ts以及src/content/docs/下的文档页index.mdx、guides/getting-started.md、guides/customize.md。对照 getting-started.md 与 customize.md 两篇示例文档可以直观看到“普通文档页 插件注入的 API Reference”在真实项目中的组织方式。完整选项列表与注意事项以 integrations/starlight/README.md 为准插件的类型定义与实现细节可进一步阅读 plugin.ts、integration.ts 与 normalize-pathname.ts。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考