scalar-api-reference

Scalar API 参考

使用与应用框架相匹配的集成，为现有应用添加交互式 API 文档。Scalar 会渲染 API 描述；请保留应用现有的描述生成器和 API 路由。

选择集成方式

检查应用的框架、软件包版本、路由约定和现有 API 描述端点。确定用户需要独立的文档路由，还是嵌入应用布局的组件。

阅读框架集成中相关的条目，然后查阅链接的指南，了解该集成的特定选项。使用项目的软件包管理器。请根据已安装版本的导出项和类型进行配置，不要假设每个封装都接受相同的选项名称。

对于纯 HTML 页面，以下是最精简的配置。通过 /openapi.json 提供 API 描述，并通过 HTTP 提供页面：

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>API Reference</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module">
      import { createApiReference } from 'https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js'

      createApiReference('#app', { url: '/openapi.json' })
    </script>
  </body>
</html>

对于基于打包工具的 JavaScript，请从 @scalar/api-reference 导入 createApiReference。对于 Vue 和 React 组件，请按Vue 和 React 样式中的说明引入集成对应的样式表。

框架集成

只阅读与应用框架对应的指南。这些是路由提示和最简入口，并非对已安装软件包 API 的替代说明。如果可以访问本地源代码，链接的指南位于 Scalar 仓库的 documentation/integrations/ 下。

应用	软件包	入口点和指南
HTML 或原生 JavaScript	@scalar/api-reference	createApiReference('#app', { url })；HTML/JS
Vue	@scalar/api-reference	使用 configuration 属性的 ApiReference 组件；Vue
React	@scalar/api-reference-react	使用 configuration 属性的 ApiReferenceReact；React
Next.js 独立路由	@scalar/nextjs-api-reference	ApiReference 返回路由处理程序；Next.js
Nuxt	@scalar/nuxt	使用 scalar 配置的 Nuxt 模块；Nuxt
Express	@scalar/express-api-reference	app.use('/reference', apiReference({ url }))；Express
Fastify	@scalar/fastify-api-reference	使用 routePrefix 和嵌套的 configuration 注册插件；Fastify
Hono	@scalar/hono-api-reference	app.get('/scalar', Scalar({ url }))；Hono
NestJS	@scalar/nestjs-api-reference	配合现有的 SwaggerModule 输出使用 apiReference({ content: document })；NestJS
FastAPI	scalar-fastapi	使用 add_scalar_reference(app) 或 get_scalar_api_reference；FastAPI
ASP.NET Core	Scalar.AspNetCore	配合 OpenAPI 文档端点使用 app.MapScalarApiReference()；ASP.NET Core

对于其他框架，请在集成目录中查找匹配的指南。不要未经核实其框架支持情况，就使用名称相似的软件包替代。

Vue 和 React 样式

Vue：

<script setup lang="ts">
import { ApiReference } from '@scalar/api-reference'
import '@scalar/api-reference/style.css'
</script>

<template>
  <ApiReference :configuration="{ url: '/openapi.json' }" />
</template>

React：

import { ApiReferenceReact } from '@scalar/api-reference-react'
import '@scalar/api-reference-react/style.css'

export const Reference = () => (
  <ApiReferenceReact configuration={{ url: '/openapi.json' }} />
)

Next.js：选择路由或页面

对于独立 HTML 文档，请创建 app/scalar/route.ts（如果应用使用 src/，则在其下创建）：

import { ApiReference } from '@scalar/nextjs-api-reference'

export const GET = ApiReference({ url: '/openapi.json' })

此方式不会继承应用的布局或 React 提供程序。对于嵌入式页面，请在客户端组件中使用 React 组件，并添加 'use client'，然后由页面导入该组件。在该客户端组件中定义浏览器回调。不要在同一路由下同时创建 page.tsx 和 route.ts。请参阅 Next.js 指南，了解元数据、CSP 和渲染器版本固定。

服务端集成差异

• Fastify 将通用选项嵌套在 configuration 下。若已注册 @fastify/swagger，且未提供显式的 content 或 url，则可以使用其生成的描述。
• NestJS 可以保留 SwaggerModule.createDocument，同时替换 UI。使用 Fastify 适配器时，请参阅其 withFastify 选项。
• FastAPI 的 Python 封装使用 openapi_url、scalar_proxy_url 和 custom_css 等名称。不要将 JavaScript 选项名称直接用作 Python 关键字参数。add_scalar_reference(app) 默认会注册 /scalar，并读取应用的 OpenAPI URL。
• ASP.NET Core 使用自己的流式配置 API。请根据项目的 .NET 版本和文档生成器阅读相应指南，再转换 JavaScript 选项。

加载 API 描述

请使用配置参考了解确切的选项格式：

• url：浏览器可访问的 URL，用于提供 JSON 或 YAML；不能是文件系统路径或 HTML 文档页面。
• content：应用已提供的 API 描述对象或 JSON/YAML 字符串。
• sources：多个 API 描述，可选包含 title、slug 和 default 选择项。为每个来源选择 url 或 content。

例如，通用 JavaScript 配置可以在两个 API 之间进行选择：

{
  sources: [
    { title: 'Public API', slug: 'public', url: '/openapi.json', default: true },
    { title: 'Admin API', slug: 'admin', url: '/admin/openapi.json' },
  ],
}

检查浏览器如何根据文档页面 URL 解析描述 URL。以斜杠开头的路径使用源站根路径；不以斜杠开头的路径则相对于页面，因此要考虑部署的基础路径。确认文档端点返回的是 API 描述，而不是登录页面或 SPA 回退页面。传入 content 会将该描述包含在浏览器接收的内容中。

身份验证和测试请求

请区分对文档页面的访问、对 API 描述的访问，以及 API 请求的身份验证。配置请求客户端的身份验证并不能保护页面或描述端点。

设置 authentication.preferredSecurityScheme 和 authentication.securitySchemes 时，请使用 API 描述中的安全方案键。请查阅配置参考，了解相应的 HTTP、API 密钥或 OAuth 流程；不要臆造通用的 apiKey 选项。不要在随应用发布的浏览器配置中存放生产环境机密。只有在需要时才启用 persistAuth；它会将凭据存储在浏览器本地存储中。

请求失败时，请检查所选的服务器 URL、请求 URL、标头、状态码和浏览器控制台。渲染出的 API 参考并不能证明其 API 请求可正常工作。优先使用 API 预期的 CORS 配置；在部署场景适合使用代理时，配置 proxyUrl。请求和凭据会经过该代理，因此不要在现有应用中悄悄添加公共代理。

外观和代码示例

从受支持的配置开始：theme、layout（modern 或 classic）、showSidebar 和 darkMode。使用主题变量或 customCss 来设置品牌样式，而不要依赖内部 DOM 选择器。对于嵌入式 API 参考，如果 Tailwind 样式发生冲突，请查看主题指南中的 CSS 层顺序说明。

使用 defaultHttpClient 搭配 targetKey 和 clientKey 来选择初始代码示例，并使用 hiddenClients 限制可用客户端。有关受支持的值和结构，请参阅配置参考。这些设置会更改代码示例的选择，而不会更改 API 的服务端实现。

从 Swagger UI 或 Redoc 迁移

复用现有的 API 描述 URL 或生成器输出。在目标路由上替换文档渲染器，并且只迁移用户需要的自定义设置。Swagger UI 和 Redoc 的选项名称不能与 Scalar 的选项互换使用。

保留描述生成、路由授权和服务端 URL。确认旧渲染器依赖没有其他用途后，再将其移除。如果有必要修改文档本身，请遵循其声明的 OpenAPI 版本，不要仅仅为了切换渲染器而升级版本。

验证和故障排除

分别检查文档路由和描述端点。在渲染后的 API 参考中，确认操作显示正常、搜索能找到已知操作，并且请求的主题或身份验证设置可见。如果需要测试请求，请使用已知的安全端点或模拟环境。

• 页面空白或样式缺失：检查浏览器错误、挂载元素、组件 CSS 导入，以及渲染器是否在浏览器上下文中运行。
• 描述加载失败：检查获取响应、URL、访问控制、CORS 和未解析的外部引用。
• 请求发往错误的主机：检查描述中的服务器以及任何已配置的服务器覆盖项。
• CSP 阻止初始化：查阅框架指南中的 nonce 和 bundle 说明；不要为了让示例正常运行而大幅削弱应用的策略。
• CDN 行为与已安装的封装不同：封装和浏览器渲染器可能使用不同版本。如需固定版本，请查看集成指南中的 bundle 或 cdn。

运行宿主应用的相关检查。报告已验证的内容和任何环境限制；不要仅凭编译结果就声称已测试浏览器行为。