在 OpenAPI 中定义 API 安全安全方案完整指南与 Scalar 的实践【免费下载链接】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与真实世界一样代码中总有需要保护的接口因此你为它们配置了安全机制。但与真实世界不同的是如何与这些安全机制交互往往并不直观——尤其是对 API 而言。这正是 OpenAPI 文档中定义安全的意义所在它让你把已经落地的认证与授权机制描述清楚帮助 API 的调用方理解安全要求并以正确的方式访问受保护的部分。这篇指南将系统讲解 OpenAPI 安全方案的几种类型、如何在 OpenAPI 文档中定义它们securitySchemes与security的完整用法、如何配合主流框架生成带安全定义的文档并深入 Scalar 的开源实现看 API 参考文档与 API 客户端是如何解析、呈现和携带这些安全凭证的。关于「安全定义」这一旧称安全方案security schemes这个概念在 OpenAPI 2原 Swagger中被称为 security definitions安全定义如今在 OpenAPI 3 中统一命名为 security schemes。OpenAPI 文档中可定义的安全类型OpenAPI 文档是对真实 API 的机器可读描述而真实 API 有各种各样的数据保护方式。你可以在文档中定义的安全类型包括API KeysAPI 密钥可以通过请求头header、查询参数query或 Cookie 三种位置发送。HTTP 认证包含 HTTP Basic用户名 密码以及 Bearer Token如 JWT。对于 Bearer 还可以定义bearerFormat例如标注为JWT。OAuth 2.0支持多种授权流程flows从标准的重定向式授权码流程到直接账号密码登录password再到应用级授权client credentials。每个流程都可以定义在哪里请求授权、在哪里用授权码换取令牌以及可用的权限范围scopes。OpenID Connect在 OAuth 2.0 之上构建允许客户端通过一个 well-known 的发现端点discovery endpoint自动获取配置信息。这些类型可以借助AND/OR逻辑自由组合并且既可以全局应用也可以只作用于单个操作operation。在 Scalar 仓库的类型定义中这四种方案被建模为SecuritySchemeObject的联合类型对应 packages/openapi-types/src/openapi-types.ts 中的HttpSecurityScheme、ApiKeySecurityScheme、OAuth2SecurityScheme和OpenIdSecurityScheme。如何定义 OpenAPI 安全securitySchemes 与 security定义 OpenAPI 安全从添加securitySchemes属性开始它声明你的 API 支持的全部安全方案。随后用security将这些方案应用到全局或单个操作上。可以把securitySchemes理解为「可用证件的类型清单」护照、驾照、工牌而security则指定「进入时需要出示哪些证件」。定义安全方案securitySchemes例如希望你的 API 文档中同时支持BasicAuth或ApiKeyAuth第一步是在components下定义它们components: securitySchemes: BasicAuth: type: http scheme: basic ApiKeyAuth: type: apiKey in: header name: X-API-Key全局应用安全方案security定义好securitySchemes后在文档顶层添加security即可全局应用。下面的示例表示整个 API 都接受「API 密钥或 Basic 认证」——注意数组中的每一项是「或」OR关系调用方只要满足其中任意一个方案即可security: - ApiKeyAuth: [] - BasicAuth: [] components: securitySchemes: # ... rest of your OpenAPI doc如果只想全局强制使用BasicAuth文档顶层只需要一个条目security: - BasicAuth: [] components: securitySchemes: BasicAuth: type: http scheme: basic description: Basic Authentication using username and password # ... rest of your OpenAPI file按操作应用安全方案要让某个操作单独使用另一种安全方案在对应 path 的 operation 上声明security即可它会覆盖而不是叠加全局设置。下面这个示例中POST /orders这个创建订单的操作单独要求ApiKeyAuthcomponents: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for protected endpoints paths: /orders: post: summary: Create new order description: Protected endpoint - requires API key security: - ApiKeyAuth: [] # This operation requires API key responses: 201: description: Order created successfully content: application/json: schema: type: object properties: orderId: type: integer status: type: string 401: description: Unauthorized - invalid or missing API key # ... rest of your OpenAPI file各类安全方案的专属属性除type和可选的description外每种安全方案还有自己的专属字段apiKey类型in取值header、query、cookie和name凭证所在的请求头名、参数名或 Cookie 名http类型scheme如basic、bearer和bearerFormat如JWToauth2类型flows其下包含authorizationCode、implicit、password、clientCredentials四种流程各自拥有authorizationUrl、tokenUrl、refreshUrl、scopes等属性openIdConnect类型openIdConnectUrl发现端点地址。这些字段的约束与 Scalar 仓库中的类型定义一一对应例如HttpSecurityScheme包含scheme与bearerFormatApiKeySecurityScheme包含name与in而OAuth2SecurityScheme的flows由四种 flow 类型组成见 packages/openapi-types/src/openapi-types.ts。当然另一面也要提醒OpenAPI 文档只是底层真实 API 的「表示层」你仍然需要在服务端真正实现这些安全机制文档并不会替你保护任何端点。组合与覆盖的语义理解security的语义对写出正确文档至关重要顶层security是全局默认值路径级别的security会覆盖它security数组中的每一项是一个 security requirement安全要求对象数组元素之间是OR关系单个 requirement 对象内部可以包含多个方案键如- {ApiKeyAuth: [], BasicAuth: []}同一对象内的多个键是AND关系调用方必须同时满足全部方案想取消全局安全要求可以在操作上写security: []。Scalar 的 API 客户端在解析这些语义时做了非常细致的处理在 packages/api-client/src/v2/blocks/scalar-auth-selector-block/helpers/security-scheme.ts 中formatSecurityRequirement会先检查 requirement 的键数量——多键AND 组合会被格式化为「A B」形式的复杂方案单键则取对应方案格式化。同时被x-scalar-ignore标记为隐藏的方案无论是独立方案还是 AND 组合中的一部分都会从认证 UI 中剔除避免出现「无法配置的半隐藏组合」。用你的框架定义安全现代 API 开发框架的一大好处是能为你生成 OpenAPI 文档因此它们通常也提供了便捷的安全定义方式。下面看三种常见框架的写法。HonoTypeScript使用zod-openapi时先向文档注册安全方案再在路由上应用它// Register the security scheme in your OpenAPI docs app.openAPIRegistry.registerComponent(securitySchemes, Bearer, { type: http, scheme: bearer, description: Enter your JWT token in the format: Bearer token, }) // Apply the security to your routes const route createRoute({ method: get, path: /protected-resource, security: [{ Bearer: [] }], handler: async (c) { const token c.req.header(Authorization) // Token validation logic here return c.json({ message: Protected data }) }, }).NETASP.NET Core在Swashbuckle中通过AddSecurityDefinition定义 Bearer 方案并用AddSecurityRequirement把它作为全局安全要求挂上再在端点上使用[Authorize]强制认证builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(options { options.AddSecurityDefinition(Bearer, new OpenApiSecurityScheme { Type SecuritySchemeType.Http, Scheme bearer, BearerFormat JWT, Description JWT Authorization header using the Bearer scheme. Example: Bearer {token} }); options.AddSecurityRequirement(new OpenApiSecurityRequirement {{ new OpenApiSecurityScheme { Reference new OpenApiReference { Type ReferenceType.SecurityScheme, Id Bearer } }, Array.Emptystring() }}); }); // Apply authentication to your endpoints app.MapGet(/protected, [Authorize] () This endpoint requires authentication) .WithOpenApi();FastAPIPython利用 FastAPI 的HTTPBasic依赖注入实现 Basic 认证并借助secrets.compare_digest做常数时间比较避免时序侧信道from fastapi import FastAPI, Depends, HTTPException, status from fastapi.security import HTTPBasic, HTTPBasicCredentials import secrets app FastAPI( titleProtected API, descriptionAPI secured with HTTP Basic Auth ) security HTTPBasic() def verify_credentials(credentials: HTTPBasicCredentials Depends(security)): # In production, use secure password comparison correct_username secrets.compare_digest(credentials.username, admin) correct_password secrets.compare_digest(credentials.password, secret) if not (correct_username and correct_password): raise HTTPException( status_codestatus.HTTP_401_UNAUTHORIZED, detailInvalid credentials, headers{WWW-Authenticate: Basic}, ) return credentials.username app.get(/secure-data/, summaryGet protected data, responses{ 401: {description: Invalid credentials}, 200: {description: Successfully authenticated} }) def secure_data(username: str Depends(verify_credentials)): return {message: fHello, {username}}从这里也能看出「框架自动生成 OpenAPI 文档」的价值所在。例如 Django 默认并不自动生成 OpenAPI 文档这会让它对接 API 参考工具或调试变得困难得多。Scalar 如何处理安全方案定义安全方案的终极目的是让 API 用起来更容易这意味着 API 参考文档和 API 客户端都需要真正理解 OpenAPI 提供的各种安全方案。API 参考文档API ReferenceScalar 的 API 参考文档支持 API Key、HTTP 与 OAuth 2.0 三类安全方案。基于你的 OpenAPI 文档以及应用到各操作上的安全方案用户可以从中选择一种并携带它发送请求。在幕后Scalar 处理了以下逻辑对应 packages/api-reference/src/features/Operation/helpers/get-required-security.ts 与 filter-selected-security.ts 等实现为每个操作正确匹配应当使用的方案区分全局security与操作级覆盖提供收集所需信息的 UI凭证输入、OAuth 授权交互在用户发起的请求上正确设置对应的认证方式请求头、查询参数、Cookie、Authorization 头等管理认证状态state处理因凭证无效或认证失败产生的错误。API 客户端API ClientAPI 客户端的功能与参考文档非常相似最大的差异在于客户端的配置状态是私有的因此可以在会话之间、集合collection之间持久化保存。这也意味着你可能同时拥有多个集合以及多个激活的安全方案。为此客户端采用了三层设计实现集中在 packages/api-client/src/v2/blocks/scalar-auth-selector-block 目录集合级存储认证值认证信息挂在 collection 上随集合一起保存支持操作级覆盖单个请求可以覆盖集合默认值按请求选择方案每次请求都允许你切换要使用的安全方案。方案选择器selector的交互性也更强可以编辑 API Key 的 name 字段也可以直接删除某个方案。在 security-scheme.ts 的getSecuritySchemeOptions中可以看到选项列表被组织为「Required authentication必需认证」「Available authentication可用认证」分组其中必需的方案来自文档的security声明可用的方案则来自securitySchemes中未被必需化且未被隐藏的条目在允许新增认证时canAddNewAuth还会附加一组「Add new authentication」预设选项。客户端还会尽可能多地预填信息自动检测安全方案从解析出的 OpenAPI 文档中识别全部securitySchemes按方案类型创建默认值结构例如 API Key 默认填入in与nameHTTP Bearer 默认scheme: bearer预配置 OAuth 流程如果文档提供了 flow 信息授权 URL、令牌 URL、scopes直接带入配置。这些「可新增认证」的预设结构定义在 auth-options.ts 中涵盖 API Key 的三种位置Header、Query、Cookie、HTTP Basic、HTTP Bearer以及 OAuth 2.0 的四种流程implicit、password、clientCredentials、authorizationCode后者还支持 PKCE 选项x-usePkce。另外值得一提的是OAuth 2.0 方案与 Bearer 方案之间存在智能联动getOauth2AcquisitionTarget见 security-scheme.ts会在 Bearer 表单上提供「通过 OAuth2 授权」的快捷入口——优先选择带authorizationCode流程的方案因为它支持刷新令牌找不到时才退回仅提供implicit流程的方案。安全与开发者体验的平衡与 Scalar 的许多功能一样团队持续在改进 OpenAPI 文档、API 参考文档与 API 客户端三者之间的联动。例如近期新增了在 API 参考与 API 客户端之间同步认证设置的能力API 参考文档可以把认证设置传递给客户端弹窗参考文档中选中的安全方案会成为客户端中的默认方案省去重复配置。安全不应该以牺牲开发者体验为代价。Scalar 提供的这些工具能帮助开发者快速、正确地完成认证进而更顺畅地测试端点、排查问题最终构建出更好也更安全的 API。Mar 26, 2025【免费下载链接】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），仅供参考
