scalar/fastify-api-reference 插件全解析为 Fastify 应用接入 Scalar API Reference 的完整实践指南【免费下载链接】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/fastify-api-reference 插件的 CHANGELOG 演进记录结合该插件在仓库中的源码实现插件主体、类型定义、构建配置、测试用例与 可运行示例系统讲解如何在 Fastify 服务中集成 Scalar API Reference包括三种 OpenAPI 文档来源、插件注册的全部路由与端点行为、配置项语义、CSP 支持、Fastify 版本兼容策略以及打包发布层面的工程细节。读完本文你将能够把 Scalar API Reference 正确接入自己的 Fastify 应用并理解各版本变更背后的设计取舍。从 CHANGELOG 看插件演进主线scalar/fastify-api-reference是一个 Fastify 插件用于把 OpenAPI/Swagger 文档渲染为美观、可交互的 API 文档页面。其版本演进到 1.68.0CHANGELOG 记录了非常密集的变更。将这些变更按主题归纳可以清晰看到插件的能力是如何一步步长出来的版本变更主题技术要点1.31.x早期构建与文档引入 esbuild 构建、新 README、移除未使用依赖1.35.0fastify/swagger 兼容修复与fastify/swagger的decorator选项不兼容的问题1.35.7尾斜杠处理支持 Fastify 新的routerOptions.ignoreTrailingSlash配置1.39.0路由注册修复修复插件前缀prefix下重定向、回调签名、request.routerPath弃用、仅传sources时 UI 路由不注册等问题1.47.0运行环境要求 Node 22LTS1.52.3架构调整迁移到scalar/client-side-rendering包统一 HTML 渲染逻辑1.58.0类型修复通过FastifySchema注解修复 Fastify 5 路由钩子类型推断错误1.59.0安全能力新增nonce选项支持严格 CSP1.62.1打包工程用 Vite 构建并将 standalone 脚本在构建时内联产物自包含、可被任意打包器处理1.65.1类型发布类型声明改为单一自包含index.d.ts修复node16/nodenext模块解析1.66.1发布流程通过 npm trusted publishing 重新发布全部包1.67.0兼容声明声明支持 Fastify v4/v5/v6Node 最低版本调整为 201.68.0端点行为修复url来源不再注册/openapi.json、/openapi.yaml本地端点修复损坏响应下文将沿着这些主题展开并给出源码级的佐证。快速开始一个最小可运行的集成示例安装依赖后即可在 Fastify 应用中注册插件。仓库中的 playground/index.ts 是一个完整的可运行参考实现其核心结构如下import fastifySwagger from fastify/swagger import Fastify from fastify import Scalar from ../src/index // 实际项目中为 scalar/fastify-api-reference const fastify Fastify({ logger: true }) // 1. 注册 fastify/swagger生成 OpenAPI 文档 await fastify.register(fastifySwagger, { openapi: { info: { title: My Fastify App, version: 1.0.0 }, components: { securitySchemes: { apiKey: { type: apiKey, name: X-Api-Key, in: header }, }, }, }, }) // 2. 定义带 schema 的路由swagger 依赖 route schema 生成文档 fastify.put{ Body: { name: string } }( /hello, { schema: { description: Greet a user, summary: Replies with a nice greeting, body: { type: object, properties: { name: { type: string } }, required: [name] }, response: { 201: { description: Successful response, type: object } }, }, }, (req, reply) reply.code(201).send({ greeting: Hello ${req.body.name} }), ) // 3. 注册 Scalar 插件渲染 API Reference await fastify.register(Scalar, { routePrefix: / }) await fastify.listen({ port: Number(process.env.PORT) || 5053, host: 0.0.0.0 })playground 将routePrefix设为/并在 Fastify 实例上注册了fastifySwagger。注意第 3 步插件注册时并未显式传入 OpenAPI 文档——此时插件会尝试从fastify/swagger自动获取。启动后访问根路径即可看到交互式 API 文档页。插件配置项详解插件完整的配置类型定义在 src/types.ts所有字段如下配置项类型默认值说明publicPathstring—已废弃类型注释标注deprecated旧版用于拼接静态资源前缀routePrefix/${string}/referenceAPI Reference 页面的挂载路径前缀会同时作用于 HTML 页面、JS 文件与 OpenAPI 端点openApiDocumentEndpoints{ json?, yaml? }{ json: /openapi.json, yaml: /openapi.yaml }定制 OpenAPI 文档暴露端点路径JSON/YAML 格式configurationPartialApiReferenceConfiguration{ _integration: fastify }透传给scalar/api-reference的通用配置对象如content、url、sources、pageTitle、nonce、主题等hooks{ onRequest?, preHandler? }—应用到本插件注册的所有路由上的 Fastify 生命周期钩子典型用途是加认证logLevelfatal \| error \| warn \| info \| debug \| trace \| silentFastify 默认覆盖插件所有路由的日志级别设silent可完全静默在源码中routePrefix会被归一化处理getRoutePrefix()fastifyApiReference.ts会去掉末尾斜杠保证所有子路径拼接正确。DEFAULT_CONFIGURATIONL57-L59向配置中注入_integration: fastify用于在引用渲染内部标识来源。OpenAPI 文档来源content / url / swagger / sources插件根据configuration决定从哪里获取 OpenAPI 文档解析逻辑集中在 fastifyApiReference.ts优先级如下content直接传入文档对象或返回文档对象的函数() spec被包装为type: content的 sourceurl传入文档 URL 字符串由浏览器端直接加载被包装为type: urlfastify/swagger当 Fastify 实例已注册fastify/swagger且fastify.swagger是函数时即未设置decorator选项调用fastify.swagger()实时生成文档sources传入引用源列表如[{ url: /openapi.json }]。若以上均未提供插件会记录一条 warning 后直接返回L108-L114不会挂掉应用对应测试见 fastifyApiReference.test.ts。值得一提的是仅提供sources时插件同样能正常注册 UI 路由——这是 1.39.0 中修复的行为见测试 L516-L539。content支持函数形式意味着可以动态提供文档例如按请求生成测试中同时覆盖了content: spec与content: () spec两种形态L189-L247。插件注册的路由与端点行为插件注册后会暴露如下路由以默认routePrefix为例每个路由都带有schema: { hide: true }源码 L24-L29用于配合fastify/swagger时从文档中隐藏这些内部路由路由行为GET /reference/返回 API Reference 的 HTML 页面text/html; charsetutf-8页面内引用本地js/scalar.jsGET /reference301 永久重定向到/reference/保证 JS 相对路径解析正确GET /reference/js/scalar.js返回内联的 Scalar standalone 脚本application/javascript; charsetutf-8GET /reference/openapi.json返回规范化后的 OpenAPI 文档 JSON仅在文档源非url时注册GET /reference/openapi.yaml返回规范化后的 OpenAPI 文档 YAML仅在文档源非url时注册尾斜杠重定向与 ignoreTrailingSlash重定向逻辑L182-L204会检查 Fastify 的ignoreTrailingSlash配置Fastify v6 中该配置位于routerOptions.ignoreTrailingSlashv4/v5 位于顶层ignoreTrailingSlash源码对两者都做了兼容判断这也是 CHANGELOG 1.35.7 与 1.67.0 分别提到的修复点。当开启ignoreTrailingSlash时 Fastify 本身就能同时响应两种路径插件便不再额外注册重定向路由1.39.0 还修复了插件外层再包一层prefix时重定向丢失前缀的问题测试见 L97-L123。url 来源不再暴露本地文档端点这是 1.68.0 的关键行为变更。此前只要注册了插件无论文档来自哪里都会注册/openapi.json与/openapi.yaml但当文档通过configuration.url提供时插件内部会把 URL 字符串当作文档内容去做归一化导致这两个端点返回损坏的响应JSON 返回 500、YAML 返回空 body。修复后url来源由浏览器直接加载用户指定的 URL插件不再重复暴露本地端点源码 L135-L139与sources来源的行为保持一致测试 L541-L565 断言这两个端点在 url 来源下返回 404。OpenAPI 文档端点的细节当文档来自content或fastify/swagger时插件用scalar/openapi-parser的normalize、toJson、toYaml对文档做解析与序列化L139-L180并设置Content-Type、Content-Disposition文件名取自文档标题经 github-slugger 生成 slug以及Access-Control-Allow-Origin: *、Access-Control-Allow-Methods: *两个 CORS 响应头。测试验证了这些端点返回内容与原文档等价且 CORS 头正确L260-L295。HTML 页面中的下载按钮即指向这些端点——即使文档由content/swagger提供渲染时也会被转成相对 URL源码 L226-L232。为 API 文档加认证hooks 选项hooks选项允许把 Fastify 生命周期钩子挂到插件注册的所有路由上HTML、JS、文档端点典型场景是给文档页面加访问控制。源码L119-L128只透传onRequest与preHandler两类钩子。测试中使用fastify/basic-auth验证了完整闭环未认证请求访问/reference与/reference/js/scalar.js均返回 401携带正确凭据后返回 200fastifyApiReference.test.tsawait fastify.register(FastifyBasicAuth, { validate: ..., authenticate: true }) await fastify.register(fastifyApiReference, { configuration: { url: /openapi.json }, hooks: { onRequest: fastify.basicAuth }, })logLevel选项则适用于希望这些内部路由不产生日志的场景测试 L457-L494 在logLevel: silent下依次请求四个路由并断言日志序列为空。严格 CSP 下的 nonce 支持1.59.0 为插件引入了nonce选项用于在严格 Content Security Policy 下运行 API Reference。传入nonce后渲染出的 HTML 会把它盖印到内联script、CDNscript标签、Scalar 自己的style标签以及一个匹配的meta propertycsp-nonce上从而允许script-src使用 nonce 而无需unsafe-inline与unsafe-eval。CHANGELOG 中的用法示例ApiReference({ url: /openapi.json, // Match this value in your script-src CSP directive. nonce: r4nd0m, })需要留意的是style-src仍需要unsafe-inline因为引用渲染会输出内联的style…属性而 CSP nonce 只能作用于script、style和link元素无法授权属性级的内联样式。所以 nonce 带来的收益是让script-src做到完全严格。在插件源码中nonce会与cdn、pageTitle一起从配置中解构出来并传给renderApiReferenceL235-L244。版本兼容与运行环境Fastify v4 / v5 / v61.67.0 通过fastify-plugin的版本范围声明源码 L261-L267{ name: scalar/fastify-api-reference, // Declare the supported Fastify range so Fastify validates it at registration // and fails fast on an incompatible host instead of breaking at runtime. fastify: 4.x || 5.x || 6.x, }这意味着 Fastify 在注册插件时会校验宿主版本遇到不支持的版本会快速失败fail fast而不是在运行时才暴露问题。该版本的测试套件运行在 Fastify v5 上同时插件已在 Fastify v6 预发布版上验证过行为一致运行时仍与 v4 保持兼容。源码中对ignoreTrailingSlash的 v4/v5/v6 差异化探测L186-L189以及用currentUrl.pathname替代已废弃的request.routerPath1.39.0 修复都是为了同时覆盖多个大版本的兼容性细节。Node.js 版本运行环境的 Node 要求随版本演进有过调整1.47.0 曾将要求提升到22LTS1.67.0 又降至20以与 Fastify v5 的 Node 要求对齐见 package.json 中的engines.node。这意味着当前版本适用于 Node 20 及以上的环境。与 fastify/swagger 的兼容1.35.0 修复了与fastify/swagger的decorator选项不兼容的问题当用户给fastify/swagger配置了自定义decorator名称时fastify.swagger函数不可用插件会检测hasPlugin(fastify/swagger)与typeof fastify.swagger function两者L97-L102确保仅在真正可调用时才使用 swagger 生成器。构建与发布工程从运行时读文件到自包含产物Vite 构建与 standalone 内联早期版本1.62.1 之前在运行时从磁盘读取scalar/api-reference的 standalone 脚本getJavaScriptFile.ts。这对开发与测试没问题但一旦用户的 Fastify 应用被打包例如打进 Docker 镜像运行时文件读取就会失效。1.62.1 起插件改用 Vite 构建并通过自定义插件scalar:inline-standalone在构建时把 standalone 脚本以?raw方式内联成字符串vite.config.ts。发布产物因此自包含、与打包器无关无论消费者的应用用 esbuild、webpack、Rollup 还是容器镜像分层打包都不会再因找不到脚本文件而崩溃。开发态playground 经tsx直接运行源码与测试态仍走运行时读取路径两种模式由构建阶段区分。单文件类型声明1.65.1 修复了moduleResolution: node16/nodenext下的类型解析问题此前.d.ts中无扩展名的相对再导出export { default } from ./fastifyApiReference会被 ESM 解析拒绝TS2834导致这些消费者的插件类型静默退化为any。修复方式是让vite-plugin-dts以rollupTypes: true产出单一自包含的index.d.tsvite.config.ts没有相对导入因此在所有模块解析设置下都能正确解析——与 Next.js 集成包保持一致。npm 发布流程1.66.1 起所有包通过 npm trusted publishing 重新发布无功能变更1.62.7 修复了 README 元数据字段命名npm 会把readme字段当作 README 文本本身导致此前受影响包在 registry 上发布成了字面量[object Object]因此 README 生成器元数据被重命名为scalarReadme见 package.json。测试验证体系插件测试覆盖了上述几乎所有行为可作为接入时自行验证的对照清单src/fastifyApiReference.test.tsHTML 返回 200、无尾斜杠 301 重定向以及ignoreTrailingSlash: true与插件外层prefix下的重定向正确性OpenAPI 文档端点fastify/swagger、content: spec、content: () spec三种来源在默认与自定义端点路径下均返回与原文等价的 JSON/YAML并带正确 CORS 头HTML 中包含js/scalar.js与指定的 spec URL、默认标题Scalar API Reference、正确text/htmlContent-Typebasic-auth 认证钩子对 HTML 与 JS 路由的 401/200 行为logLevel: silent下所有插件路由静默未提供任何文档源时仅告警不崩溃hasPlugin仍为 true仅sources提供时 UI 路由正常、文档端点 404url来源同样不暴露文档端点。深入阅读插件主体实现路由注册、文档源解析、版本声明等核心逻辑插件类型定义全部配置项与默认值可运行示例fastify/swagger 本插件的完整集成测试用例行为契约的完整验证构建配置standalone 内联与类型打包包元信息Node 版本要求、导出结构与依赖变更日志完整版本演进记录【免费下载链接】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），仅供参考