
> 标签：`#OpenAPI` `#components` `#复用` `#definitions` `#API治理`

---

## 实践问题

很多公司的后台，技术架构上采用 SaaS 模式：几十个微服务共享同一套「400 参数错误 / 401 未授权 / 500 内部错误」结构。

Swagger 2.0 文档里，`definitions`、`parameters`、`responses`、`securityDefinitions` 散落顶层，新人第一次找公共错误体，经常问：「咱家的 `ErrorResponse` 到底在哪个文件里？」

更糟的是，同一错误结构在三个服务里各抄一份。某天产品要求错误体增加 `traceId`，你得改三处，漏改一处，SDK 生成出来就不一致。文档越写越长，维护成本指数级上升。

---

## API思想进化

**复用是 API 治理的复利：把公共定义收进统一命名空间，文档越长大越省维护成本。**

API 规范不仅是给前端看的文档，更是全链路的「单一事实来源」。公共模型、公共错误、公共参数必须有一处统一归口，否则微服务一多，契约必然分裂。

---

## 旧写法 vs 新写法

![03-components-tree.png](https://developer.qcloudimg.com/http-save/yehe-11563618/cc2d9fd08f9e0a367a11682f159216fc.png)

*图：Swagger 2.0 顶层散点 vs OpenAPI 3.0+ components 树*

### 2.0：顶层散点

Swagger 2.0 把可复用定义平铺在根级别。

问题：
- 四种定义分类不清，容易混乱；
- 没有统一命名空间，跨文件复用靠 `$ref` 硬路径；
- 不支持 `requestBodies`、`headers`、`examples` 等高级复用。

```yaml
swagger: '2.0'
host: api.example.com
basePath: /v1
definitions:
  ErrorResponse:
    type: object
    properties:
      code:
        type: integer
      message:
        type: string
parameters:
  PageParam:
    name: page
    in: query
    type: integer
responses:
  NotFound:
    description: 未找到
securityDefinitions:
  bearerAuth:
    type: apiKey
    in: header
    name: Authorization
paths:
  /users: ...
```



### 3.0+：统一 `components` 命名空间

OpenAPI 3.0 引入 `components`，把可复用定义按类型分类。

所有公共定义归到 `components` 下，查找路径统一、分类清晰、工具链解析一致。

```yaml
openapi: '3.0.3'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        traceId:
          type: string
  responses:
    NotFound:
      description: 未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
```



### 3.2：再扩 `pathItems` 与 `mediaTypes`

OpenAPI 3.2 在 `components` 中新增两类复用：

```yaml
openapi: '3.2.0'
components:
  pathItems:
    userBase:
      get:
        summary: 查询用户
      post:
        summary: 创建用户
  mediaTypes:
    JsonProblem:
      schema:
        $ref: '#/components/schemas/Problem'
```

`pathItems` 可以复用整段 Path Item，`mediaTypes` 可以复用 Media Type Object。对于上百个接口的大型 API，这意味着整段 CRUD 路径都可以复用，而不是复制粘贴。

![03-reuse-cost-curve.png](https://developer.qcloudimg.com/http-save/yehe-11563618/c86db80986201e16a30a95e28d485884.png)

*图：复用让 API 文档越长大越省成本*

### 案例：GlobalPay OpenApi Common Schemas（3.0.3）

这是一个 Domain（可复用组件库），本身就是为复用而生，来源：`https://app.swaggerhub.com/domains/globalsolutions-184/CommonSchemas/2.4.0`

这种「公共 Schema Domain」正是 `components` 思想的工程化落地：错误体只定义一次，所有业务 API 通过 `$ref` 引用。

```yaml
openapi: 3.0.3
info:
  title: GlobalPay OpenApi Common Schemas
  version: 2.4.0
components:
  schemas:
    Error:
      type: object
      properties:
        error_code:
          type: string
        detailed_error_code:
          type: string
        detailed_error_description:
          type: string
```



### 案例：Acme Components（3.1.0）

```yaml
openapi: 3.1.0
info:
  title: Acme Components
  version: 1.0.0
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
```

来源：`https://app.swaggerhub.com/domains/smartbear-playground/TestExternal3.1Domain/1.0.0`

---

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

- **GlobalPay OpenApi Common Schemas（3.0.3）**：`https://app.swaggerhub.com/domains/globalsolutions-184/CommonSchemas/2.4.0`
  - 专门放公共 schemas，是 `components` 思想的最佳示范。
- **Acme Components（3.1.0）**：`https://app.swaggerhub.com/domains/smartbear-playground/TestExternal3.1Domain/1.0.0`
  - 轻量 components 示例。
- **Azure AI Foundry Models Service（3.2.0）**：`https://app.swaggerhub.com/apis/westriverconsulting/azure-ai-foundry-models-service/v1`
  - 大型 API 中 `components` 的复杂用法。

---

## 落地 checklist

1. **按复用频率分层**：高频复用（公共错误、公共模型）进 `components`，一次性 schema 就近内联。
2. **错误响应抽成 `components.responses`**：比如 `NotFound`、`BadRequest`、`Unauthorized`，全站统一引用。
3. **多服务共享同一 Domain**：像 GlobalPay 那样建一个 Common Schemas Domain，业务 API 用 `$ref` 引用。
4. **3.2 用 `components.pathItems`**：把 CRUD 整段路径复用，避免复制粘贴。
5. **老项目迁移**：把顶层 `definitions` → `components.schemas`，`parameters` → `components.parameters`，`responses` → `components.responses`，`securityDefinitions` → `components.securitySchemes`。
6. **命名规范**：`components.schemas` 用 PascalCase，`components.parameters` 用 camelCase，团队统一。

---

## 下一篇预告

OpenAPI演进录 | 04-Cookie 参数和整串查询，旧版 OpenAPI 写不了？

标签：#OpenAPI #components #复用 #definitions #API治理

OpenAPI演进录 | 03-通用对象放哪儿？API中的component重用

聊聊开放 API 的 Swagger 描述规范

后端

开发工具

架构设计

"OpenAPI组件复用提升API治理效率，通过components统一管理公共错误、参数和模型，避免重复定义。Swagger2.0升级OpenAPI3.0+后，利用components命名空间实现跨服务复用，降低维护成本。案例展示GlobalPay等企业如何通过公共SchemaDomain实现API一致性，推荐高频复用内容放入components分层管理。"

代码解释

SaaS

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

"OpenAPI组件复用提升API治理效率，通过components统一管理公共错误、参数和模型，避免重复定义。Swagger2.0升级OpenAPI3.0+后，利用components命名空间实现跨服务复用，降低维护成本。案例展示GlobalPay等企业如何通过公共SchemaDomain实现API一致性，推荐高频复...

OpenAPI演进录 | 03-通用对象放哪儿？API中的component重用-腾讯云开发者社区-腾讯云

OpenAPI演进录 | 03-通用对象放哪儿？API中的component重用

OpenAPI演进录 | 03-通用对象放哪儿？API中的component重用

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐