尧图网站建设 
Scalar Agent Key 完全指南为生产环境的 API 引用配置 Agent 鉴权与文档自动同步【免费下载链接】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 中Agent 是驱动 API 引用API Reference内嵌聊天控件Sparkle 图标与 MCP 服务器背后的智能层。本指南围绕 Agent Key 这一核心鉴权机制讲解其产生原因、创建步骤、在 API Reference 配置中的注入方式、本地开发与生产环境的差异化行为以及如何借助 GitHub Actions 让 OpenAPI 文档与 Registry 持续同步确保你的 Agent 始终拥有最新的 API 信息。读完本文你将掌握如何为生产部署获取 Agent Key如何通过sourcesagent配置把 Key 绑定到具体 OpenAPI 文档如何按需禁用 Agent 或隐藏添加 API控件以及如何建立文档的自动化同步流水线。Agent Key 是什么生产环境的第一道鉴权门槛Agent Key 是 Scalar 为生产环境部署设计的访问凭证它与 Registry 中特定的 OpenAPI 文档一一绑定而不是一把万能钥匙。这意味着每个 Key 只授权访问其绑定的那份 API 文档天然限制了越权范围没有 Key 时Agent 在非本地环境默认不启用——API 引用中的聊天控件不会渲染Key 在 API Reference 配置中通过sources数组内嵌在agent.key字段里随请求携带。从源码结构看这一设计对应 packages/api-reference/src/hooks/use-agent.ts 中的useAgent钩子agentEnabled计算属性默认通过isLocalUrl(window.location.href)判断当前页面是否为本地地址本地开发自动放行而生产环境则由配置显式控制。在 packages/api-reference/src/components/ApiReference.vue 中可以看到完整的启用逻辑——先检查agent.disabled是否被设置为true再检查当前激活文档的配置中是否设置了agent.key若配置了agent.disabled: trueAgent 被强制禁用否则只要对应 source 的agent.key存在Agent 即被启用本地localhost页面则无需任何 Key 即可体验完整聊天功能。创建 Agent Key三步完成绑定按照官方文档生产环境获取 Agent Key 的完整流程如下进入 Registry 管理页打开 Scalar Dashboard准备 OpenAPI 文档直接上传你的 OpenAPI/Swagger 文档或通过 GitHub Actions 连接仓库实现自动同步详见下文用 GitHub Actions 保持文档同步一节创建 Key导航到目标文档详情页在文档级操作中创建 Agent Key。创建完成后你会得到一个形如your-agent-scalar-key的字符串它已经与该文档绑定只能用于该文档的 Agent 访问。在 API Reference 中注入 Agent Key拿到 Key 后把它加入 API Reference 的初始化配置。关键点在于Agent 配置是**逐 sourcePer-source**的——Key 必须放在sources数组中对应条目的agent对象里Scalar.createApiReference(#app, { sources: [ { url: https://registry.scalar.com/your-namespace/apis/your-api/latest?formatjson, agent: { key: your-agent-scalar-key, }, }, ], })这里url指向 Registry 中该文档的 JSON 地址?formatjson表示请求 JSON 格式agent.key就是刚才创建的绑定 Key。该配置的实际消费链路可以追溯到 packages/api-reference/src/components/AgentScalar/AgentScalarChatInterface.vue 以及 ApiReference.vue 中configList[activeSlug]?.agent的取值逻辑——即聊天界面渲染时读取的是当前激活 source 的agent配置对象。配置参考key、disabled 与 hideAddApiagent配置对象支持以下属性完整参考见 documentation/guides/agent/api-reference.md属性类型默认值说明keystringundefined你的 Agent Key生产环境必填disabledbooleanfalse是否禁用 Agent含本地环境hideAddApibooleanfalse是否隐藏添加 API控件仅显示预加载或 Registry 文档三个属性的使用场景分别如下。本地开发零配置即可用Agent 在http://localhost上默认启用无需任何配置每个会话自带 10 条免费消息。最小示例Scalar.createApiReference(#app, { url: /openapi.json, })此时聊天图标Sparkle会出现在 API Reference 界面的左上角。这一本地默认放行的行为正对应 use-agent.ts 中agentEnabled ?? computed(() isLocalUrl(window.location.href))的兜底逻辑。生产部署没有 Key 就没有聊天生产环境必须配置 Key否则聊天控件不会渲染。除了单文档写法还可以为多个 API 分别指定各自的 Key——每个 source 独立鉴权Scalar.createApiReference(#app, { sources: [ { url: https://registry.scalar.com/your-namespace/apis/first-api/latest?formatjson, agent: { key: key-for-first-api, }, }, { url: https://registry.scalar.com/your-namespace/apis/second-api/latest?formatjson, agent: { key: key-for-second-api, }, }, ], })禁用与收敛disabled 与 hideAddApi全局禁用 Agent包括 localhost时把disabled放在顶层agent对象中可覆盖所有 sourceScalar.createApiReference(#app, { agent: { disabled: true, }, sources: [ { url: /api/v1/openapi.json }, { url: /api/v2/openapi.json }, ], })隐藏添加 API控件当通过sources或 Registry 预加载了特定 API 时可在对应 source 的agent中设置hideAddApi: true界面将不再显示 API按钮和从数十个 API 中添加上下文区块用户只能使用你预加载的文档Scalar.createApiReference(#app, { sources: [ { url: https://registry.scalar.com/your-namespace/apis/your-api/latest?formatjson, agent: { key: your-agent-scalar-key, hideAddApi: true, }, }, ], })hideAddApi在实现层面会透传给 AgentScalarChatInterface.vue 的hideAddApiprop见其第 33 行的绑定用于控制聊天界面内添加 API入口的渲染。用 GitHub Actions 保持文档同步Agent Key 绑定的是 Registry 中的文档版本。为了让 Agent 始终掌握最新 API 信息生产环境建议通过 GitHub Actions 自动把 OpenAPI 文档推送到 Registry替代手动上传。完整方案见 documentation/guides/registry/github-actions.md核心是scalar/cli的三条命令document validate校验、auth login登录、registry publish发布。基础工作流push 即同步# .github/workflows/push-to-scalar-registry.yml name: Push OpenAPI document to the Registry on: push: branches: - main jobs: push-to-scalar-registry: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Use Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json - name: Log in to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Push to Registry run: npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json工作流先校验文档合法性再用 GitHub Secrets 中保存的SCALAR_API_KEY登录最后按--namespace命名空间与--slugAPI 标识发布到 Registry。任何对main分支api/openapi.json的推送都会自动触发同步。多环境部署按分支切换命名空间需要区分开发、预发、生产环境的项目可基于分支条件设置不同的命名空间# .github/workflows/publish-openapi-document.yml name: Publish OpenAPI Document on: push: paths: - api/**/*.yaml branches: - main - development jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Install Scalar CLI run: npm install -g scalar/cli - name: Authenticate Scalar env: SCALAR_API_KEY: ${{ secrets.SCALAR_API_KEY }} run: scalar auth login - name: Set production namespace if: github.ref refs/heads/main run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_PRODUCTION }} $GITHUB_ENV - name: Set development namespace if: github.ref refs/heads/development run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_DEVELOPMENT }} $GITHUB_ENV - name: Publish API run: scalar registry publish ./api/openapi.json --namespace $NAMESPACE --slug your-apimain分支发布到生产命名空间development分支发布到开发命名空间同一个文档在不同环境保持隔离版本。合并前校验Pull Request 守卫对追求质量的团队可以在 PR 阶段先校验文档防止无效 OpenAPI 进入 Registry# .github/workflows/validate-openapi.yml name: Validate OpenAPI on Pull Request on: pull_request: paths: - api/** jobs: validate: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json多 API 仓库矩阵批量发布一个仓库包含多个 API 时可用strategy.matrix批量发布每个 API 独立校验与发布# .github/workflows/publish-multiple-apis.yml name: Publish Multiple APIs on: push: branches: - main paths: - apis/** jobs: publish-apis: runs-on: ubuntu-latest strategy: matrix: api: - name: user-api file: apis/user-api/openapi.json slug: user-api - name: product-api file: apis/product-api/openapi.json slug: product-api - name: order-api file: apis/order-api/openapi.json slug: order-api steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate ${{ matrix.api.name }} run: npx scalar/cli document validate ${{ matrix.api.file }} - name: Login to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish ${{ matrix.api.name }} run: | npx scalar/cli registry publish \ --namespace ${{ vars.SCALAR_NAMESPACE }} \ --slug ${{ matrix.api.slug }} \ ${{ matrix.api.file }}Secrets 配置上述工作流依赖两个 GitHub 配置项仓库 Secrets 中的SCALAR_API_KEY用于认证以及仓库 Variables 中的命名空间变量如SCALAR_NAMESPACE_PRODUCTION、SCALAR_NAMESPACE。获取 API Key 请前往 Scalar Dashboard 的 API Keys 页面再将其添加到 GitHub 仓库的 Secrets 中避免明文暴露。免费额度与进阶阅读免费限制内嵌聊天每会话提供 10 条免费消息localhost环境无需 Key 即可使用完整聊天功能。超出后如需升级可参考 documentation/guides/agent/pricing.md。MCP 场景Agent Key 与 MCP 安装Installation是两条独立的鉴权路径。MCP 服务器默认私有团队成员用 Personal Access Token 连接外部用户通过 OAuth 授权进入上游 API 凭证由 Scalar 执行层持有、Agent 永远看不到。详见 documentation/guides/agent/mcp.md 与 documentation/guides/agent/authentication/index.md。更多接入方式从 OpenAPI 到 Agent 的完整三步流程上传 → 配置安装与鉴权 → 通过 MCP URL 或 Agent SDK 连接参见 documentation/guides/agent/getting-started.md 与 documentation/guides/agent/sdk.md。小结Agent Key 是 Scalar 将内嵌智能聊天安全地带入生产环境的关键机制Key 与 Registry 文档绑定实现最小权限sources内嵌配置让多文档各自鉴权disabled与hideAddApi提供细粒度控制GitHub Actions 流水线则保证文档与 Agent 的持续同步。结合 use-agent.ts 中本地默认启用、生产显式授权的默认策略你可以在零配置体验与生产安全之间取得平衡——本地开发免 Key 快速验证生产环境用绑定 Key 严格把关。【免费下载链接】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），仅供参考 Scalar Agent Key 完全指南：为生产环境的 API 引用配置 Agent 鉴权与文档自动同步
Scalar Agent Key 完全指南为生产环境的 API 引用配置 Agent 鉴权与文档自动同步【免费下载链接】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 中Agent 是驱动 API 引用API Reference内嵌聊天控件Sparkle 图标与 MCP 服务器背后的智能层。本指南围绕 Agent Key 这一核心鉴权机制讲解其产生原因、创建步骤、在 API Reference 配置中的注入方式、本地开发与生产环境的差异化行为以及如何借助 GitHub Actions 让 OpenAPI 文档与 Registry 持续同步确保你的 Agent 始终拥有最新的 API 信息。读完本文你将掌握如何为生产部署获取 Agent Key如何通过sourcesagent配置把 Key 绑定到具体 OpenAPI 文档如何按需禁用 Agent 或隐藏添加 API控件以及如何建立文档的自动化同步流水线。Agent Key 是什么生产环境的第一道鉴权门槛Agent Key 是 Scalar 为生产环境部署设计的访问凭证它与 Registry 中特定的 OpenAPI 文档一一绑定而不是一把万能钥匙。这意味着每个 Key 只授权访问其绑定的那份 API 文档天然限制了越权范围没有 Key 时Agent 在非本地环境默认不启用——API 引用中的聊天控件不会渲染Key 在 API Reference 配置中通过sources数组内嵌在agent.key字段里随请求携带。从源码结构看这一设计对应 packages/api-reference/src/hooks/use-agent.ts 中的useAgent钩子agentEnabled计算属性默认通过isLocalUrl(window.location.href)判断当前页面是否为本地地址本地开发自动放行而生产环境则由配置显式控制。在 packages/api-reference/src/components/ApiReference.vue 中可以看到完整的启用逻辑——先检查agent.disabled是否被设置为true再检查当前激活文档的配置中是否设置了agent.key若配置了agent.disabled: trueAgent 被强制禁用否则只要对应 source 的agent.key存在Agent 即被启用本地localhost页面则无需任何 Key 即可体验完整聊天功能。创建 Agent Key三步完成绑定按照官方文档生产环境获取 Agent Key 的完整流程如下进入 Registry 管理页打开 Scalar Dashboard准备 OpenAPI 文档直接上传你的 OpenAPI/Swagger 文档或通过 GitHub Actions 连接仓库实现自动同步详见下文用 GitHub Actions 保持文档同步一节创建 Key导航到目标文档详情页在文档级操作中创建 Agent Key。创建完成后你会得到一个形如your-agent-scalar-key的字符串它已经与该文档绑定只能用于该文档的 Agent 访问。在 API Reference 中注入 Agent Key拿到 Key 后把它加入 API Reference 的初始化配置。关键点在于Agent 配置是**逐 sourcePer-source**的——Key 必须放在sources数组中对应条目的agent对象里Scalar.createApiReference(#app, { sources: [ { url: https://registry.scalar.com/your-namespace/apis/your-api/latest?formatjson, agent: { key: your-agent-scalar-key, }, }, ], })这里url指向 Registry 中该文档的 JSON 地址?formatjson表示请求 JSON 格式agent.key就是刚才创建的绑定 Key。该配置的实际消费链路可以追溯到 packages/api-reference/src/components/AgentScalar/AgentScalarChatInterface.vue 以及 ApiReference.vue 中configList[activeSlug]?.agent的取值逻辑——即聊天界面渲染时读取的是当前激活 source 的agent配置对象。配置参考key、disabled 与 hideAddApiagent配置对象支持以下属性完整参考见 documentation/guides/agent/api-reference.md属性类型默认值说明keystringundefined你的 Agent Key生产环境必填disabledbooleanfalse是否禁用 Agent含本地环境hideAddApibooleanfalse是否隐藏添加 API控件仅显示预加载或 Registry 文档三个属性的使用场景分别如下。本地开发零配置即可用Agent 在http://localhost上默认启用无需任何配置每个会话自带 10 条免费消息。最小示例Scalar.createApiReference(#app, { url: /openapi.json, })此时聊天图标Sparkle会出现在 API Reference 界面的左上角。这一本地默认放行的行为正对应 use-agent.ts 中agentEnabled ?? computed(() isLocalUrl(window.location.href))的兜底逻辑。生产部署没有 Key 就没有聊天生产环境必须配置 Key否则聊天控件不会渲染。除了单文档写法还可以为多个 API 分别指定各自的 Key——每个 source 独立鉴权Scalar.createApiReference(#app, { sources: [ { url: https://registry.scalar.com/your-namespace/apis/first-api/latest?formatjson, agent: { key: key-for-first-api, }, }, { url: https://registry.scalar.com/your-namespace/apis/second-api/latest?formatjson, agent: { key: key-for-second-api, }, }, ], })禁用与收敛disabled 与 hideAddApi全局禁用 Agent包括 localhost时把disabled放在顶层agent对象中可覆盖所有 sourceScalar.createApiReference(#app, { agent: { disabled: true, }, sources: [ { url: /api/v1/openapi.json }, { url: /api/v2/openapi.json }, ], })隐藏添加 API控件当通过sources或 Registry 预加载了特定 API 时可在对应 source 的agent中设置hideAddApi: true界面将不再显示 API按钮和从数十个 API 中添加上下文区块用户只能使用你预加载的文档Scalar.createApiReference(#app, { sources: [ { url: https://registry.scalar.com/your-namespace/apis/your-api/latest?formatjson, agent: { key: your-agent-scalar-key, hideAddApi: true, }, }, ], })hideAddApi在实现层面会透传给 AgentScalarChatInterface.vue 的hideAddApiprop见其第 33 行的绑定用于控制聊天界面内添加 API入口的渲染。用 GitHub Actions 保持文档同步Agent Key 绑定的是 Registry 中的文档版本。为了让 Agent 始终掌握最新 API 信息生产环境建议通过 GitHub Actions 自动把 OpenAPI 文档推送到 Registry替代手动上传。完整方案见 documentation/guides/registry/github-actions.md核心是scalar/cli的三条命令document validate校验、auth login登录、registry publish发布。基础工作流push 即同步# .github/workflows/push-to-scalar-registry.yml name: Push OpenAPI document to the Registry on: push: branches: - main jobs: push-to-scalar-registry: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Use Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json - name: Log in to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Push to Registry run: npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json工作流先校验文档合法性再用 GitHub Secrets 中保存的SCALAR_API_KEY登录最后按--namespace命名空间与--slugAPI 标识发布到 Registry。任何对main分支api/openapi.json的推送都会自动触发同步。多环境部署按分支切换命名空间需要区分开发、预发、生产环境的项目可基于分支条件设置不同的命名空间# .github/workflows/publish-openapi-document.yml name: Publish OpenAPI Document on: push: paths: - api/**/*.yaml branches: - main - development jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Install Scalar CLI run: npm install -g scalar/cli - name: Authenticate Scalar env: SCALAR_API_KEY: ${{ secrets.SCALAR_API_KEY }} run: scalar auth login - name: Set production namespace if: github.ref refs/heads/main run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_PRODUCTION }} $GITHUB_ENV - name: Set development namespace if: github.ref refs/heads/development run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_DEVELOPMENT }} $GITHUB_ENV - name: Publish API run: scalar registry publish ./api/openapi.json --namespace $NAMESPACE --slug your-apimain分支发布到生产命名空间development分支发布到开发命名空间同一个文档在不同环境保持隔离版本。合并前校验Pull Request 守卫对追求质量的团队可以在 PR 阶段先校验文档防止无效 OpenAPI 进入 Registry# .github/workflows/validate-openapi.yml name: Validate OpenAPI on Pull Request on: pull_request: paths: - api/** jobs: validate: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json多 API 仓库矩阵批量发布一个仓库包含多个 API 时可用strategy.matrix批量发布每个 API 独立校验与发布# .github/workflows/publish-multiple-apis.yml name: Publish Multiple APIs on: push: branches: - main paths: - apis/** jobs: publish-apis: runs-on: ubuntu-latest strategy: matrix: api: - name: user-api file: apis/user-api/openapi.json slug: user-api - name: product-api file: apis/product-api/openapi.json slug: product-api - name: order-api file: apis/order-api/openapi.json slug: order-api steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate ${{ matrix.api.name }} run: npx scalar/cli document validate ${{ matrix.api.file }} - name: Login to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish ${{ matrix.api.name }} run: | npx scalar/cli registry publish \ --namespace ${{ vars.SCALAR_NAMESPACE }} \ --slug ${{ matrix.api.slug }} \ ${{ matrix.api.file }}Secrets 配置上述工作流依赖两个 GitHub 配置项仓库 Secrets 中的SCALAR_API_KEY用于认证以及仓库 Variables 中的命名空间变量如SCALAR_NAMESPACE_PRODUCTION、SCALAR_NAMESPACE。获取 API Key 请前往 Scalar Dashboard 的 API Keys 页面再将其添加到 GitHub 仓库的 Secrets 中避免明文暴露。免费额度与进阶阅读免费限制内嵌聊天每会话提供 10 条免费消息localhost环境无需 Key 即可使用完整聊天功能。超出后如需升级可参考 documentation/guides/agent/pricing.md。MCP 场景Agent Key 与 MCP 安装Installation是两条独立的鉴权路径。MCP 服务器默认私有团队成员用 Personal Access Token 连接外部用户通过 OAuth 授权进入上游 API 凭证由 Scalar 执行层持有、Agent 永远看不到。详见 documentation/guides/agent/mcp.md 与 documentation/guides/agent/authentication/index.md。更多接入方式从 OpenAPI 到 Agent 的完整三步流程上传 → 配置安装与鉴权 → 通过 MCP URL 或 Agent SDK 连接参见 documentation/guides/agent/getting-started.md 与 documentation/guides/agent/sdk.md。小结Agent Key 是 Scalar 将内嵌智能聊天安全地带入生产环境的关键机制Key 与 Registry 文档绑定实现最小权限sources内嵌配置让多文档各自鉴权disabled与hideAddApi提供细粒度控制GitHub Actions 流水线则保证文档与 Agent 的持续同步。结合 use-agent.ts 中本地默认启用、生产显式授权的默认策略你可以在零配置体验与生产安全之间取得平衡——本地开发免 Key 快速验证生产环境用绑定 Key 严格把关。【免费下载链接】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），仅供参考