[!info] related notes

• 所属 MOC: 后端开发 MOC
• 上层概念: 接口规范
• 相关详解: OpenAPI规范详解
• 相关实践: nodejs-express-openapi-swagger-integration, import-swagger-docs-from-project
• 相关资源: APIFox, postman, postman-mock-documentation-and-spec-hub, postman-vs-apifox

OpenAPI 与 Swagger

一句话定义

OpenAPI 是描述 HTTP API 契约的规范；Swagger 则是围绕这份规范形成的一组工具和历史命名。

范围

这篇笔记只解释 OpenAPI 和 Swagger 的关系、边界和常见误解，不展开完整规范语法，也不展开具体框架接入步骤。

为什么容易混在一起

很多团队第一次接触 API 文档体系时，看到的是：

• Swagger UI 页面
• swagger-jsdoc
• “导入 Swagger 文档”

于是会把：

• 规范本身
• 工具链
• 页面展示

统称成“Swagger”。

但更稳定的理解方式是把它拆开：

• 接口规范：契约层，回答 API 应该如何被描述
• OpenAPI：把契约写成标准化、可机读的 YAML / JSON 文件
• Swagger：消费这份契约的一组工具和生态名词

OpenAPI 是什么

OpenAPI Specification（OAS）是一种 API 描述标准，用来描述：

• 路径与方法
• 参数与请求体
• 响应结构
• 认证方式
• 错误模型
• examples 与 schema 复用

它为 API 设计、文档、Mock、代码生成和验证提供共同输入；规范文件本身不会执行认证、验证请求或保证运行中的服务符合描述。

Swagger 是什么

Swagger Specification 是 OpenAPI 的历史前身；OpenAPI 2.0 文档仍使用 swagger: “2.0” 顶层字段，3.x 使用 openapi 版本字段。Swagger 品牌下的 UI、Editor、Codegen 是工具，支持哪些规范版本需分别确认。

常见语境包括：

• Swagger UI：把 OpenAPI 文件渲染成交互式文档
• Swagger Editor：编辑 OpenAPI 文件
• Swagger Codegen：基于规范生成代码

所以现在说“Swagger”，很多时候其实是在说“围绕 OpenAPI 的工具链”。

它们的关系

可以把两者理解成：

• OpenAPI 更像标准
• Swagger 更像基于这份标准的一组工具实现

一个容易记的类比是：

• OpenAPI 像 HTML 标准
• Swagger UI / Editor / Codegen 像围绕这个标准工作的浏览器和开发工具

对比与易混淆点

OpenAPI / Swagger 不等于接口规范本身的全部

接口规范 是更上层的设计约束。

OpenAPI 是把这套约束写成可机读契约的常用方式，但不是所有 API 规范讨论都必须先落到某个工具页面。

Swagger UI 不等于 API 设计

Swagger UI 只是展示层。

真正重要的是你是否已经有一份清晰、一致、可验证的 OpenAPI 契约。

工具平台不等于规范

Postman、APIFox 这类平台可以导入、展示、测试和 Mock OpenAPI，但它们消费的是契约，不是契约本身。

版本与导入边界

• OpenAPI 2.0、3.0 与 3.1 的 schema/关键字并非完全互换；3.1 与 JSON Schema 的对齐方式也不同于 3.0。
• YAML/JSON 是表示格式，不决定文档属于哪一规范版本。
• 工具接受文件不代表完整保留外部引用、认证、示例或扩展字段，应验证实际导入/导出的差异。

来源：OpenAPI Specification。

从哪里继续

• 如果要系统理解语法和工作流，继续看 OpenAPI规范详解
• 如果要在 Node.js / Express 项目里落地，继续看 nodejs-express-openapi-swagger-integration
• 如果要把产出的 OpenAPI 文档导入工具平台，继续看 import-swagger-docs-from-project