
> 标签：`#OpenAPI` `#securitySchemes` `#mTLS` `#mutualTLS` `#认证`

---

## 实践问题

很多公司的后台，技术架构上采用 SaaS 模式：金融、政务类接口要求双向 TLS（mTLS），客户端和服务端互相验证证书。Swagger 2.0 的 `securityDefinitions` 只有三种类型：`basic`、`apiKey`、`oauth2`，根本描述不了 mTLS。

结果安全方案只能写进接口注释：「本接口需双向 TLS，请联系运维配置证书。」网关配置和文档两张皮，框架无法自动注入认证逻辑，每次对接都要人工核对证书策略。安全本该是契约的一部分，却成了文档的灰色地带。

---

## API思想进化

**认证是契约的一部分：把安全方案标准化声明，框架才能自动注入、自动校验。**

安全不是部署后才考虑的事情。如果规范能声明「这个接口需要 mTLS」或「这个接口用 OAuth2 的哪个 scope」，网关、SDK、测试工具就能统一理解并执行，而不是靠人脑记忆。

---

## 旧写法 vs 新写法

![09-security-schemes.png](https://developer.qcloudimg.com/http-save/yehe-11563618/9d9f22832737c1985474cd73d2a24cbb.png)

*图：OpenAPI securitySchemes 类型演进与 OAuth2 流程*

### 2.0：securityDefinitions 类型有限

Swagger 2.0 的安全方案类型只有三种：

```yaml
swagger: '2.0'
securityDefinitions:
  BasicAuth:
    type: basic
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: https://example.com/oauth/authorize
    tokenUrl: https://example.com/oauth/token
```

没有 mTLS，没有 openIdConnect。金融接口的双向 TLS 完全无法在契约中声明。

### 3.0：securitySchemes 移入 components

OpenAPI 3.0 把安全方案从顶层 `securityDefinitions` 移到 `components.securitySchemes`，并扩展类型：

```yaml
openapi: '3.0.3'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    oauth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: 读取权限
            write: 写入权限
    openIdAuth:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
```

类型扩展到 `http`、`apiKey`、`oauth2`、`openIdConnect`，但仍没有 mTLS。

### 3.2：新增 `type: mutualTLS`

OpenAPI 3.2 终于补上 mTLS：

```yaml
openapi: '3.2.0'
components:
  securitySchemes:
    mtlsAuth:
      type: mutualTLS
```

然后在全局或操作级引用：

```yaml
security:
  - mtlsAuth: []

paths:
  /sensitive:
    get:
      security:
        - mtlsAuth: []
      responses:
        '200':
          description: 成功
```

![09-mtls-handshake.png](https://developer.qcloudimg.com/http-save/yehe-11563618/93f35b5e1519c11dadd6cb0f92e880cc.png)

*图：mTLS 双向认证握手*

### 案例：Modern Petstore API（3.2.0）

```yaml
openapi: 3.2.0
# ...
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.petstoreapi.com/oauth/authorize
          tokenUrl: https://auth.petstoreapi.com/oauth/token
          scopes:
            read:pets: 读取宠物信息
            write:pets: 修改宠物信息
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

来源：`https://app.swaggerhub.com/apis/hcm-a45/S3V2/1.0.0`

Modern Petstore 展示了 3.2 中 `securitySchemes` 的丰富用法，但未直接使用 `mutualTLS`（公开 API 中 mTLS 用例确实极少）。

### 案例：Azure AI Foundry Models Service（3.2.0）

Azure AI Foundry 也使用 `securitySchemes` 声明 API Key 和 Bearer Token 认证。

来源：`https://app.swaggerhub.com/apis/westriverconsulting/azure-ai-foundry-models-service/v1`

---

## 真实案例佐证
（优先 SwaggerHub）

- **Modern Petstore API（3.2.0）**：`https://app.swaggerhub.com/apis/hcm-a45/S3V2/1.0.0`
  - 展示 `securitySchemes` 中 OAuth2、Bearer 的声明方式。
- **Azure AI Foundry Models Service（3.2.0）**：`https://app.swaggerhub.com/apis/westriverconsulting/azure-ai-foundry-models-service/v1`
  - 展示 API Key 和 Bearer Token 的安全方案。
- **Swagger Petstore - OpenAPI 3.0**：`https://app.swaggerhub.com/apis/smartbear/0-0-0/1.0.0`
  - 展示 3.0 的基础安全方案。

> 注：公开 API 中 `type: mutualTLS` 的真实用例极少，金融接口通常不会把 mTLS 契约公开到 SwaggerHub。本文 mTLS 示例参考 OpenAPI 3.2 官方规范。

---

## 落地 checklist

1. **新项目 3.2+ 需要 mTLS**：直接用 `type: mutualTLS`。
2. **3.0/3.1 项目需要 mTLS**：只能写进 `description` 或外部文档，契约层面无法声明；建议升级到 3.2。
3. **全局 security + 操作级覆盖**：全局声明默认安全方案，匿名接口用 `security: []` 覆盖。
4. **OAuth2 写清 scopes**：每个 scope 的权限范围必须描述清楚。
5. **迁移路径**：2.0 `securityDefinitions` → 3.0 `components.securitySchemes` → 3.2 新增 `mutualTLS`。
6. **网关联动**：把 `securitySchemes` 与网关证书策略、鉴权插件打通，避免文档与配置两张皮。

---

## 下一篇预告

OpenAPI演进录 | 10 - 非标准方法、文档互引、接口分组

标签：#OpenAPI #securitySchemes #mTLS #mutualTLS #认证

OpenAPI演进录 | 09 - 双向 TLS 怎么写进 OpenAPI 契约？

聊聊开放 API 的 Swagger 描述规范。这 11 篇文章以「OpenAPI 演进录」为主线，系统梳理了从 Swagger 2.0 到 OpenAPI 3.2 的规范演进与工程实践，讲解如何用契约准确描述真实 API 中的环境、内容协商、复用、参数、可空、多态、事件、流式、安全与治理等复杂场景。

开发工具

网络与通信

安全

OpenAPI 3.2新增mutualTLS类型，解决金融政务类API双向认证需求。从Swagger2.0到OpenAPI3.2，安全方案标准化演进让mTLS、OAuth2等认证方式可声明式配置，实现网关、SDK、测试工具自动校验，消除文档与实现差异。

代码解释

SaaS

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenAPI演进录 | 09 - 双向 TLS 怎么写进 OpenAPI 契约？-腾讯云开发者社区-腾讯云

OpenAPI演进录 | 09 - 双向 TLS 怎么写进 OpenAPI 契约？

OpenAPI演进录 | 09 - 双向 TLS 怎么写进 OpenAPI 契约？

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐