API Meta Information

API Specification 必须包含 API metadata

API 规范必须包含完整的 API metadata，以支持 API 生命周期管理和治理。

OpenAPI Specification 必须提供以下信息：

字段	描述
`#/info/title`	唯一且具有业务含义的 API 名称
`#/info/version`	遵循语义化版本规范的 API 版本
`#/info/description`	API 的清晰描述

同时必须提供以下扩展字段：

字段	描述
`#/info/x-api-id`	API 唯一且不可变的标识符
`#/info/x-audience`	API 的目标使用者范围

示例：

yaml

openapi: 3.0.1

info:
  title: User Management API
  description: 用户管理相关接口。
  version: 1.2.0
  x-api-id: user-management-api-123456
  x-audience: company-internal

API 版本必须使用 Semantic Versioning

OpenAPI 中：

shell

#/info/version

表示 API Specification 的版本。

该版本必须遵循 Semantic Versioning 2.0。

格式必须为：

text

<MAJOR>.<MINOR>.<PATCH>

例如：

text

1.3.7

版本升级规则

MAJOR 主版本

当 API 出现不兼容变化时，必须升级 MAJOR。

例如：

删除已有接口
删除或重命名请求字段
以破坏兼容性的方式修改响应结构
修改 API 行为导致现有消费者无法继续使用

示例：

text

1.0.0 -> 2.0.0

MINOR 次版本

当新增功能且保持向后兼容时，升级 MINOR。

例如：

新增 API Endpoint
新增可选参数
新增不会影响现有客户端的 Response 字段

示例：

text

1.2.0 -> 1.3.0

PATCH 修订版本

用于向后兼容的问题修复或文档修改。

例如：

修正描述错误
修正文档示例
修复接口说明问题

示例：

text

1.3.0 -> 1.3.1

API Version 与软件版本区别

API Version 描述的是：

对外 API Contract 的变化。

它不是软件发布版本。

以下变化通常不需要修改 API Version：

内部代码重构
修改内部实现
更新依赖库
修改数据库实现

只要 API Contract 没有变化，API Version 保持不变。

API Version 限制

API Version 不允许包含：

Pre-release 标识

错误：

text

1.0.0-alpha

Build Metadata

错误：

text

1.0.0+build123

只允许：

text

MAJOR.MINOR.PATCH

例如：

yaml

info:
  version: 1.3.7

API Identifier

每个 API Specification 必须提供唯一且不可变的 API ID。

API ID 用于：

跟踪 API 演进历史
管理 API 生命周期
关联不同版本 API
支持自动兼容性检查

API ID 在生命周期内不可修改。

示例：

yaml

info:
  x-api-id: user-management-api-123456

推荐定义：

yaml

x-api-id:
  type: string
  description: API 唯一不可变标识。

示例：

yaml

info:
  x-api-id: d0184f38-b98d-11e7-9c56-68f728c1ba70

API ID 表示 API 本身，API Version 表示该 API 的具体演进阶段。

示例：

text

API ID:
user-management-api

Versions:
1.0.0
1.1.0
1.2.0
2.0.0

所有版本都属于同一个 API 生命周期。

API Audience 分类

每个 API 必须定义目标使用范围。

Audience 用于确定：

API 治理规则
文档公开范围
安全策略
变更流程
Review 要求

字段：

shell

#/info/x-audience

允许值：

yaml

x-audience:
  type: string

支持的值：

text

internal
company-internal
external-partner
external-public

Audience 定义

Audience	分类	描述
internal	系统内部	仅供同一团队维护的组件或子系统内部使用
company-internal	组织内部	可以跨团队使用，但不会暴露给外部
external-partner	外部合作伙伴	提供给授权合作伙伴
external-public	公开 API	面向公网用户

Audience 示例

内部 API

yaml

info:
  x-audience: internal

示例：

text

同一个系统内部的 Service A -> Service B

公司内部 API

yaml

info:
  x-audience: company-internal

示例：

text

组织内不同团队之间的 Service A -> Service B

合作伙伴 API

yaml

info:
  x-audience: external-partner

示例：

text

企业系统 -> 合作伙伴系统

公共 API

yaml

info:
  x-audience: external-public

示例：

text

互联网开放 API

Audience 规则

一个 API Specification 必须只有一个 Audience。
不允许同时声明多个 Audience。
如果一个 API 中包含不同 Audience 的接口，应拆分为多个 API Specification。

错误：

yaml

x-audience:
  - internal
  - external-public

正确：

API A：

yaml

x-audience: internal

API B：

yaml

x-audience: external-public