
> 标签：`#OpenAPI` `#Swagger` `#接口契约` `#WSDL` `#SOAP` `#REST`

---

## 实践问题

很多公司的后台，技术架构上采用 SaaS 模式：服务被拆成几十个微服务，同一套 API 要同时面向内部网关、外部合作伙伴、前端客户端和自动化测试工具。

◆但接口契约的「定义版本」和「工具版本」却成了一团乱麻——老系统甩来一份 WSDL/SOAP 契约，团队却只有 OpenAPI 工具链，编辑器读不懂、网关解析不了、SDK 生成器直接报错；

◆仓库里 Swagger 2.0 的 `host`/`basePath`/`definitions` 和新项目的 OpenAPI 3.x 的 `servers`/`components` 互相听不懂；

◆代码生成器对 `nullable`、`oneOf`、`webhooks` 的支持各说各话，升级一个版本就可能让所有可选字段变必填。

看业界，DCOM、CORBA 江湖上见不到了。SOAP/WSDL 等接口还在银行政务系统里，最晚遗留接口被调用着。而 OpenAPI 这个 2015 年才从 Swagger 改名过来的规范，偏偏成了赢家与默认选项。


---

## 接口描述规范代际演进

![00-evolution-timeline.png](https://developer.qcloudimg.com/http-save/yehe-11563618/667f734d7072d395dbb25d0f72e696b4.png)

*图：接口描述规范从 IDL 到 OpenAPI 的演进*

### 第 0 代：IDL 思想萌芽

上世纪 80 年代，分布式系统先有了 **IDL（Interface Definition Language）** 思想：用与编程语言无关的文本描述接口名、入参、出参、异常，再据此生成客户端桩代码和服务端骨架。

Sun RPC / ONC RPC 配套的 **XDR**、OSF 的 **DCE RPC**，都确立了「先写契约、再生成代码」的工作范式。这个范式直到今天都没死，只是换了个载体。

### 第 1 代：二进制 RPC 时代

90 年代是局域网组件调用的黄金年代。**CORBA** 用 CORBA IDL 描述跨语言对象接口，ORB 负责对象定位与调用；**DCOM** 则是微软基于 DCE RPC 谱系做的 Windows 跨机器扩展。

它们的共同点是：先有 IDL 契约 → 生成桩代码 → 进程或机器间远程调用。

但致命伤也很统一：二进制协议、防火墙极难穿透、平台锁定严重。**它们解决的问题是「内网组件互相调用」，不是「公网服务对外开放」。**

### 第 2 代：WebService 时代

互联网兴起后，企业需要穿透 80 端口防火墙。于是 RPC 被封装进 HTTP+XML：

- **XML-RPC（1998）**：极简过渡方案；
- **SOAP（1999/2000）**：规定 HTTP 报文内的 XML 信封结构；
- **WSDL（2000/2001）**：用 XML 描述接口地址、方法名、参数结构、报文格式，相当于 WebService 时代的「接口契约文档」。

WSDL 与后来的 OpenAPI 职责完全对齐——都是接口契约描述规范，差别只在载体：WSDL = XML + SOAP RPC，OpenAPI = JSON/YAML + HTTP REST。

SOAP/WSDL 确实解决了防火墙穿透问题，但代价是报文沉重、工具昂贵、强 RPC 风格与互联网资源语义格格不入。

### 第 3 代：REST + Swagger

2000 年 Roy Fielding 的博士论文定义了 **REST**：用 HTTP 语义（GET/POST/PUT/DELETE）操作资源，报文换成更轻量的 JSON。

2010 年 **Swagger** 出现，专门用 JSON/YAML 描述 HTTP REST API，自带调试页面和代码生成。它要做的就是一件事：**替代笨重的 WSDL**。

### 第 4 代：OpenAPI 事实标准

2015 年，Swagger 项目交由 **OpenAPI Initiative（Linux 基金会）** 托管，规范正式更名 **OpenAPI Specification（OAS）**。此后只迭代 OpenAPI，不再叫 Swagger。

- 2017 年 OpenAPI 3.0 发布；
- 2021 年 OpenAPI 3.1 完全对齐 JSON Schema 2020-12；
- 2025 年 OpenAPI 3.2 继续扩展非标准操作、流式媒体、整体查询串、mTLS 等能力。

今天，OpenAPI 3.x 已经是 REST API 契约的事实标准：编辑器、Mock、网关解析、测试、SDK 生成、API 治理全链路沿用同一份描述文件。

### 现代并行分支

古老的 IDL 契约思想从未消失，只是换载体适配不同网络环境：

| 分支 | 契约机制 | 传输 | 适用场景 |
|------|---------|------|---------|
| **gRPC** | Protobuf IDL | HTTP/2 | 服务间高性能内网调用 |
| **Dubbo** | 自有协议 / Protobuf | TCP/HTTP | 国内微服务内网 RPC |
| **Thrift** | Thrift IDL | 多协议 | 跨语言二进制 RPC |
| **GraphQL** | SDL | HTTP | 前端按需取数 |
| **AsyncAPI** | 复刻 OpenAPI 结构 | 消息队列 | 事件驱动 / 异步 API |

**边界说明**：OpenAPI 只管 HTTP 类 API（REST / Web），对二进制 RPC（gRPC、Dubbo、Thrift）无能为力，那些由各自的 IDL 体系描述。事件 / 流式场景由 AsyncAPI 或 OpenAPI 3.2 的 webhooks / 流式媒体字段覆盖。

---


## API 思想进化

![00-tool-chain-panorama.png](https://developer.qcloudimg.com/http-save/yehe-11563618/d829113bcbdca406546be117be8516ad.png)

*图：OpenAPI 工具链全景*

规范不是凭空设计，而是为了填上前一代的坑：**让接口在公网被机器读懂，才是 API 契约的终极胜负手。**

OpenAPI 的每一条语法都不是「发明」，而是「选择」——在特定网络环境、特定工具链、特定工程规模下，选择了一种最能被机器消费、最能降低协作成本的描述方式。掌握来龙去脉，才知道每个语法点为何存在。

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

公开 API 的存量数据最能验证「谁赢了」。在 SwaggerHub 搜索几个关键词，结果不言自明：

- `https://app.swaggerhub.com/search?q=openapi` —— OpenAPI 定义的存量占据绝对主导；
- `https://app.swaggerhub.com/search?q=soap` —— SOAP/WSDL 的公开存量明显萎缩；
- `https://app.swaggerhub.com/search?q=swagger` —— 仍有大量公开 API 口头称 Swagger，正好印证「Swagger/OpenAPI 名字混淆」至今存在。

这组对比不是技术优劣的简单投票，而是「公网机器可读契约」这一胜负手的直接结果：XML + SOAP 太重，二进制 RPC 穿不透防火墙，只有 JSON/YAML + HTTP REST 的组合同时满足「轻量」「可穿透」「工具链丰富」三个条件。

---

## 落地 checklist

1. **新项目默认 OpenAPI 3.1+**，别再写 WSDL/SOAP。
2. **维护老 SOAP 系统时**，用 OpenAPI 在网关层做「门面」逐步迁移，而非一夜重写。
3. **内网高性能服务间调用**优先用 gRPC / Dubbo，别硬套 OpenAPI。
4. **对外 HTTP API**一律用 OpenAPI，编辑器、Mock、网关、SDK、测试工具链即开即用。
5. **Swagger 与 OpenAPI 的关系**要随时澄清：Swagger 是工具生态和品牌，OpenAPI 是规范名称；2015 年后规范只叫 OpenAPI。

---

## 下一篇预告

文章 01 · 环境一变就改文档？把基地址从契约里踢出去

标签：#OpenAPI #Swagger #接口契约 #WSDL #SOAP #REST

序章-DCOM WSDL 都输了，Swagger/OpenAPI 凭什么赢

聊聊开放 API 的 Swagger 描述规范

后端

架构设计

编程语言

探索OpenAPI如何成为REST API契约的事实标准，从IDL到SOAP/WSDL的演进历程，分析现代API工具链的挑战与解决方案。了解Swagger与OpenAPI的关系，掌握微服务架构下接口契约管理的最佳实践。

自动化测试工具

消息队列

防火墙

Windows

Linux

SaaS

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

序章-DCOM WSDL 都输了，Swagger/OpenAPI 凭什么赢-腾讯云开发者社区-腾讯云

序章-DCOM WSDL 都输了，Swagger/OpenAPI 凭什么赢

序章-DCOM WSDL 都输了，Swagger/OpenAPI 凭什么赢

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐