Scalar 对 OpenAPI mutualTLS 认证方案的完整支持类型保留、coercion 修复与认证 UI 的只读引导【免费下载链接】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/scalaroutput_articleScalar 对 OpenAPI mutualTLS 认证方案的完整支持类型保留、coercion 修复与认证 UI 的只读引导mTLS双向 TLS认证在 OpenAPI 规范中属于标准的安全方案类型之一但由于它在 TLS 握手层完成证书交换、不产生可供用户填写的 name/value 对或 token许多 API 工具在实现时都会把它“降级”处理导致文档与客户端表现不一致。Scalar 在scalar/workspace-store、scalar/types与scalar/api-client三个包中同时修复了这一行为mutualTLS 安全方案的类型在解析与 coercion 后得以保留认证 UI 也会针对 mutualTLS 及浏览器无法支持的 broker 凭证类型给出明确的只读引导文案。本文将结合 .changeset/mutual-tls-scheme.md 的变更说明深入剖析该修复在类型模型、数据校验、工作区存储与认证界面四个层面的落地方式并给出可直接用于 OpenAPI 文档的配置示例。变更背景mutualTLS 方案为何会被“误伤”OpenAPI 3.x 规范定义了五种安全方案类型apiKey、http、mutualTLS、oauth2、openIdConnect。其中mutualTLS是最特殊的一种——正如 packages/types/src/entities/security-scheme.ts 中的注释所描述的Mutual TLS presents a client certificate at the TLS layer, so there is no name/value pair or token for the user to enter.也就是说客户端证书在 TLS 握手时由浏览器或客户端软件自动呈现请求层面没有可编辑的凭证字段。因此在解析器内部它往往被当作一个“多余的”类型在数据校验zod coercion时被回退到联合类型的第一个成员——apiKey于是认证界面便渲染出一个 Name/Value 输入表单既无法真正填写证书又给用户造成“可以在这里输入证书”的错误暗示。本次变更的核心目标有两个类型保留mutualTLS安全方案在 ingestion文档导入与 coercion 之后仍然保持mutualTLS类型而不是被降级为apiKey表单只读引导认证 UI 针对 mutualTLS以及浏览器无法发送的 AsyncAPI broker 凭证类型显示只读的引导性说明而不是渲染无意义的输入框。类型模型为 mutualTLS 定义独立的 schema在 packages/types/src/entities/security-scheme.ts 中scalar/types为 mutualTLS 定义了独立的 zod schemaconst oasSecuritySchemeMutualTls commonProps.extend({ type: z.literal(mutualTLS), }) export const securityMutualTlsSchema oasSecuritySchemeMutualTls.merge(extendedSecuritySchema) export type SecuritySchemeMutualTls z.infertypeof securityMutualTlsSchema可以看到type被限定为字面量mutualTLS不存在被解析成其他类型的空间它继承了commonProps可选的description与x-scalar-ignore与extendedSecuritySchemauid与nameKey但没有继承任何凭证值字段如value、username、token这从类型层面直接表达了“mutualTLS 没有可填写的凭证”这一语义。在联合类型层面oasSecuritySchemeSchema将 mutualTLS 与 apiKey、http、oauth2、openIdConnect 并列security-scheme.ts#L242-L248而面向工作区使用的securitySchemeSchema则采用z.discriminatedUnion(type, [...])按type字段精确分派security-scheme.ts#L251-L270这保证了在解析阶段就能稳定地区分出 mutualTLS 方案。测试印证类型保留与五种方案并存packages/types/src/entities/security-scheme.test.ts 中的 “Combined Security Scheme” 测试同时校验了 apiKey、http、mutualTLS、openIdConnect、oauth2 五种方案const mutualTls { type: mutualTLS, uid: mutual-tls123, } // ... expect(securitySchemeSchema.safeParse(apiKey).success).toBe(true) expect(securitySchemeSchema.safeParse(http).success).toBe(true) expect(securitySchemeSchema.safeParse(mutualTls).success).toBe(true)仅凭type: mutualTLS与一个uid即可通过校验说明该类型模型刻意保持最小化——它不要求也不允许任何凭证字段。存储层workspace-storeingestion 时不再降级scalar/workspace-store是 Scalar 对 OpenAPI/AsyncAPI 文档进行导入、校验与持久化的核心模块。本次修复在三个位置落地严格模式 schemav3.1 / v3.2在 packages/workspace-store/src/schemas/v3.1/strict/security-scheme.ts 与 v3.2/strict/security-scheme.ts 中MutualTlsSchema仅由DescriptionSchema与type: Type.Literal(mutualTLS)组合而成并且被显式列入SecuritySchemeObjectSchemaDefinition的联合类型中const MutualTlsSchema compose( DescriptionSchema, Type.Object({ type: Type.Literal(mutualTLS), }), ) export const SecuritySchemeObjectSchemaDefinition Type.Union([ ApiKeySchema, HttpSchema, MutualTlsSchema, OAuth2, OpenIdConnect, ])宽松开放模式 schemapackages/workspace-store/src/schemas/v3.1/openapi/index.ts#L527-L533 中同样定义了mutualTlsSecuritySchemetypeName: MutualTlsSecuritySchemeObject确保不同解析模式下类型定义保持一致。ingestion 回归测试packages/workspace-store/src/client.test.ts#L4388-L4416 中的测试完整验证了该修复it(preserves a mutualTLS security scheme during ingestion, async () { const store createWorkspaceStore() await store.addDocument({ name: mtls, document: { openapi: 3.1.0, info: { title: Example, version: 1.0 }, paths: { /ping: { get: { security: [{ mutualTLS: [] }], responses: { 200: { description: OK } } } }, }, components: { securitySchemes: { mutualTLS: { type: mutualTLS, description: some desc }, }, }, }, }) const document store.workspace.documents[mtls] const scheme getResolvedRef(getResolvedRef(document.components)?.securitySchemes?.mutualTLS) expect(scheme?.type).toBe(mutualTLS) expect(scheme?.description).toBe(some desc) })测试注释明确记录了此前的缺陷行为“Coercion used to downgrade the unknown type to the first union member (apiKey), which is why the UI rendered a Name/Value form.”coercion 曾将未知类型降级为联合类型的第一个成员 apiKey这正是 UI 渲染出 Name/Value 表单的原因。修复后方案类型与description都能原样保留。一个可直接使用的 OpenAPI 3.1 配置示例结合上述实现下面是一个完整的、能够在 Scalar 中正确渲染只读引导的 mutualTLS 配置与测试用例结构一致openapi: 3.1.0 info: title: Mutual TLS Example version: 1.0.0 paths: /ping: get: security: - mutualTLS: [] responses: 200: description: OK components: securitySchemes: mutualTLS: type: mutualTLS description: | Client certificates are presented during the TLS handshake. No header, query or cookie credential is required.关键点type必须精确写为mutualTLS大小写敏感否则会被判定为其他方案类型description可选但建议写上说明性文本它会在认证 UI 中随方案一并展示测试断言了description的保留在security中引用时使用mutualTLS: []的形式与 OpenAPI 规范一致mTLS 方案没有可选的 scope 数组内容。认证 UI从“错误的输入框”到“只读引导”类型修复的最终收益体现在 packages/api-client/src/v2/blocks/scalar-auth-selector-block/components/RequestAuthTab.vue 的认证面板中。该组件按scheme?.type分派渲染逻辑httpbasic/bearer渲染 Username/Password 或 Token 输入行apiKey渲染 Name可选与 Value 输入行oauth2/openIdConnect渲染 flow 标签页与 OAuth2 配置一组 AsyncAPI broker 凭证类型userPassword、plain、scramSha256、scramSha512、X509、symmetricEncryption、asymmetricEncryption、gssapi显示只读说明mutualTLS显示只读引导未知类型显示“not supported yet”提示缺失type提示检查文档。对应的模板片段RequestAuthTab.vue#L601-L607!-- Mutual TLS credentials are chosen during the browser-managed TLS handshake. -- div v-else-ifscheme?.type mutualTLS classtext-c-3 flex items-center justify-center border-t p-4 px-4 text-center text-xs text-balance Mutual TLS authenticates with a client certificate presented during the TLS handshake, so there is nothing to enter here. /div而 AsyncAPI broker 凭证的只读提示位于 RequestAuthTab.vue#L584-L599!-- Browser WebSocket connections cannot apply these broker credentials. -- div v-else-if scheme?.type userPassword || scheme?.type plain || ... scheme?.type gssapi classtext-c-3 flex items-center justify-center border-t p-4 px-4 text-center text-xs text-balance Credentials for this AsyncAPI security scheme are not sent by the browser client. /div这两类分支的共同点是不再渲染任何RequestAuthDataTableInput输入框而是用说明文案替代从 UI 层面杜绝了“填写无意义字段”的困惑。测试印证无输入框 正确的文案packages/api-client/src/v2/blocks/scalar-auth-selector-block/components/RequestAuthTab.test.ts#L312-L327 中的测试精确断言了该行为it(explains that mutual TLS does not accept browser credentials, () { const wrapper mountWithProps({ securitySchemes: { BrokerAuth: { type: mutualTLS, description: A scheme type without a dedicated input UI, }, }, selectedSecuritySchemas: { BrokerAuth: [], }, }) expect(wrapper.text()).toContain(client certificate presented during the TLS handshake) expect(wrapper.findAllComponents(RequestAuthDataTableInput)).toHaveLength(0) })断言点非常明确文案包含 “client certificate presented during the TLS handshake”且输入组件数量为 0。这与 RequestAuthTab.test.ts#L288-L310 中 AsyncAPIapiKeyin: user仍会渲染单个 Value 输入框的用例形成对照——前者是“浏览器无法发送凭证”后者是“仍有值需要填写”。方案的标签与整体渲染逻辑为了让读者理解 mutualTLS 分支在认证面板中的位置这里补充标签生成逻辑RequestAuthTab.vue#L157-L183switch (scheme.type) { case apiKey: return ${capitalizedName}: ${scheme.in} // e.g. ApiKeyAuth: header case openIdConnect: case oauth2: return ${capitalizedName}: ${currentFlow} // e.g. OAuth2: authorizationCode case http: return ${capitalizedName}: ${scheme.scheme} // e.g. HttpAuth: bearer default: return capitalizedName // mutualTLS 命中此分支 }mutualTLS 没有in、scheme、flows等附加属性因此标签直接使用方案名如MutualTLS与其“无附加参数”的语义一致。在 RequestAuthTab.vue#L111-L126 中方案通过getResolvedRef(securitySchemes[name])解析并仅在oauth2/openIdConnect时计算可见 flow 键其余类型含 mutualTLS不参与 flow 相关逻辑。关联扩展x-scalar-ignore与认证方案的隐藏本次修复之外mutualTLS 方案同样受 documentation/openapi.md 中记载的x-scalar-ignore扩展控制在任意安全方案包括 mutualTLS上添加x-scalar-ignore: true即可将其从认证选择器中整体隐藏。该扩展在 packages/types/src/entities/security-scheme.ts 的commonProps与 workspace-store 的XScalarIgnoreSchema中均有实现适用于“某些方案无法在浏览器中运行”的场景如因 CORS 受限的 Client Credentials flow。对于 mutualTLS 这类需要客户端环境配合的方案若你希望文档保持纯净、不向用户展示认证面板可以这样配置components: securitySchemes: mtls: type: mutualTLS description: Certificate-based authentication at the TLS layer. x-scalar-ignore: true小结本次变更解决了 OpenAPI mutualTLS 认证方案在 Scalar 全链路中的一个真实缺陷涉及三个层面层面位置修复内容类型模型packages/types/src/entities/security-scheme.ts为mutualTLS定义独立 schema不携带任何凭证字段存储层packages/workspace-store/src/schemas/v3.1/strict/security-scheme.ts、v3.1/openapi/index.ts严格/开放模式均显式声明mutualTLS类型ingestion 不再降级为apiKey认证 UIpackages/api-client/src/v2/blocks/scalar-auth-selector-block/components/RequestAuthTab.vuemutualTLS 与浏览器不支持的 broker 凭证类型改为只读引导文案不再渲染输入框两条回归测试security-scheme.test.ts 与 client.test.ts、RequestAuthTab.test.ts从“类型可解析、ingestion 保留、UI 无输入框”三个维度锁定了行为防止未来重构时再次回退。对于使用 mTLS 保护 API 的团队而言这意味着OpenAPI 文档中的mutualTLS方案在 Scalar 的 API Reference 与 API Client 中会被如实呈现——认证面板明确告知证书在 TLS 握手阶段由客户端提供、无需也不应填写任何凭证而不会被误导性的 Name/Value 表单所替代。 /output_article【免费下载链接】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），仅供参考