# OpenAPI 3.2.1 规范更新：支持 OAuth 2.0 Device Flow 与安全元数据发现

> OpenAPI 3.2.1 规范于 2026 年 9 月发布，主要更新包括：1) 新增 OAuth 2.0 Device Authorization Flow (RFC 8628) 支持，允许在 `OAuth Flows Object` 中配置 `deviceAuthorization`；2) 新增 `oauth2MetadataUrl` 字段，支持 RFC 8414 元数据发现；3) 新增 `deprecated` 字段，用于标记弃用的安全方案；4) 明确 `Security Requirement Object` 的 URI 引用解析规则，解决组件名称与 URI 冲突问题。这些更新增强了 API 安全机制的描述能力，但要求工具链更新以支持新字段。

原文：/knowledge/openapi-3-2-1-%E8%A7%84%E8%8C%83%E6%9B%B4%E6%96%B0-%E6%94%AF%E6%8C%81-oauth-2-0-device-flow-%E4%B8%8E%E5%AE%89%E5%85%A8%E5%85%83%E6%95%B0%E6%8D%AE%E5%8F%91%E7%8E%B0

OpenAPI 规范（OAS）3.2.1 版本于 2026 年 9 月 10 日发布，在保持与 3.2.x 系列兼容的基础上，重点增强了安全机制的描述能力。该版本引入了对 OAuth 2.0 Device Authorization Flow (RFC 8628) 的原生支持，新增了 `oauth2MetadataUrl` 字段以支持 RFC 8414 元数据发现，并增加了 `deprecated` 字段以标记弃用的安全方案。同时，3.2.1 版本对 Security Requirement Object 的 URI 引用解析逻辑进行了更明确的定义，以解决组件名称与 URI 冲突时的歧义问题。


## OAuth 2.0 Device Flow 与元数据发现支持

在 3.2.1 版本之前，OpenAPI 规范主要支持 OAuth 2.0 的常见流程（implicit, password, client credentials, authorization code）。3.2.1 版本正式将 OAuth 2.0 Device Authorization Flow (RFC 8628) 纳入规范，允许在 `OAuth Flows Object` 中配置该流程。

### 配置示例

在 `Security Scheme Object` 中，通过 `flows` 字段添加 `deviceAuthorization` 配置：

```yaml
type: oauth2
flows:
  deviceAuthorization:
    deviceAuthorizationUrl: https://example.com/oauth/device
    tokenUrl: https://example.com/oauth/token
    scopes:
      read:data: Read sensitive data
      write:data: Write sensitive data
```

其中：
- `deviceAuthorizationUrl`：设备授权 URL，必须为 TLS 保护的 URL。
- `tokenUrl`：令牌 URL，用于设备轮询获取访问令牌。
- `scopes`：可用的权限范围。

此外，规范新增了 `oauth2MetadataUrl` 字段，用于指向 OAuth 2.0 授权服务器的元数据 URL（RFC 8414），支持自动发现授权端点。该字段要求使用 TLS。

```yaml
type: oauth2
oauth2MetadataUrl: https://example.com/.well-known/oauth-authorization-server
flows:
  authorizationCode:
    authorizationUrl: https://example.com/oauth/authorize
    tokenUrl: https://example.com/oauth/token
    scopes:
      read:data: Read data
```


## 安全方案弃用标记

3.2.1 版本引入了 `deprecated` 布尔字段，允许在 `Security Scheme Object` 中标记安全方案为已弃用。当 `deprecated` 设置为 `true` 时，消费者应避免使用该安全方案。默认值为 `false`。

```yaml
type: oauth2
deprecated: true
description: Implicit flow is deprecated. Use Authorization Code with PKCE instead.
flows:
  implicit:
    authorizationUrl: https://example.com/oauth/dialog
    scopes:
      read:data: Read data
```

这一变更有助于 API 提供者明确标识不再推荐使用的安全机制（如 OAuth Implicit Flow），引导消费者迁移到更安全的方案（如 Authorization Code with PKCE）。


## Security Requirement Object 的 URI 引用解析规则

3.2.1 版本对 `Security Requirement Object` 的 URI 引用解析逻辑进行了更明确的定义，以解决组件名称与 URI 冲突时的歧义问题。

### 解析规则

1. **组件名称优先**：如果属性名与 `Components Object` 下声明的安全方案名称完全相同，则必须将其视为组件名称。
2. **URI 引用冲突处理**：若要引用一个单段相对 URI 引用（如 `foo`），且该名称与组件名称（如 `#/components/securitySchemes/foo`）冲突，应使用 `.` 路径段（如 `./foo`）来明确引用 URI。
3. **不推荐使用 URI 风格的组件名称**：使用看起来像 URI 的安全方案组件名称是不推荐的，因为组件名称匹配优先于 URI 解析，这与直觉相悖。

### 示例

```yaml
# 使用组件名称
security:
  - petstore_auth:
      - write:pets
      - read:pets

# 使用 URI 引用（避免与组件名称冲突）
security:
  - ./external_auth:
      - read:data
```

这一变更旨在提高多文档 OpenAPI 描述中安全方案引用的清晰度和一致性，减少工具链解析时的歧义。


## 工具链支持与兼容性

OpenAPI 3.2.1 是 3.2.x 系列的补丁版本，旨在修复错误并提供澄清。支持 OAS 3.2 的工具应兼容所有 3.2.* 版本。然而，由于 3.2.1 引入了新的安全机制字段（如 `deviceAuthorization`、`oauth2MetadataUrl`、`deprecated`），旧版工具可能无法正确解析或生成这些字段。

目前，主流代码生成工具（如 OpenAPI Generator）对 3.2.1 新特性的支持情况需查阅其最新文档或 GitHub 仓库。建议在使用 3.2.1 规范时，确保工具链已更新以支持新增的安全机制字段，特别是在涉及 OAuth 2.0 Device Flow 和元数据发现的场景中。

### 安全考虑

- **TLS 要求**：`oauth2MetadataUrl`、`deviceAuthorizationUrl`、`tokenUrl` 和 `refreshUrl` 均要求使用 TLS。
- **弃用方案**：OAuth Implicit Flow 已被 OAuth 2.0 Security Best Current Practice 建议弃用，推荐使用 Authorization Code Grant with PKCE。
- **安全过滤**：OpenAPI 描述中的 `Paths Object` 或 `Path Item Object` 可以为空，以支持访问控制列表（ACL）约束，允许文档提供者精细控制可见性。

<!-- knowledgefill:references -->
## 参考资料

- [OpenAPI Specification v3.2.1](https://spec.openapis.org/oas/v3.2.1.html)
- [https://github.com/OAI/OpenAPI-Specification/commits/main/versions/3.2.1.md](https://github.com/OAI/OpenAPI-Specification/commits/main/versions/3.2.1.md)
- [OpenAPI Specification v3.2.1](https://spec.openapis.org/oas/latest.html)
