什么是OpenAPI ？
能够向其他人（您的同事、合作伙伴或您提供 API 的组织）提供 API 定义对于开展业务至关重要。API 经济的成功取决于使用与 API 消费者相关的语言，反复、简洁和确定地执行此操作。
API 规范语言提供了执行此操作的标准化方法。您的 API 可以用不可知的术语进行描述，将它们与任何特定的编程语言解耦。API 规范的使用者不需要了解应用程序的内部结构，也不需要尝试学习 Lisp 或 Haskell（如果您选择用 Lisp 或 Haskell 来编写应用程序）。他们可以从您的 API 规范中准确地理解他们需要什么，这些规范是用简单且富有表现力编写的语言。
OpenAPI 规范 (OAS) 正是实现了从 API 提供者到 API 消费者的知识转移。它是用于描述 API 的开放标准，允许您提供以 JSON 或 YAML 文档编码的 API 规范。它提供了全面的术语词典，反映了 API 领域中常见的概念，嵌入了 HTTP 和 JSON 的基础知识。当与支持工具结合使用时，它可以基于简单的文档提供丰富的体验。
OpenAPI使用规定的格式来描述 HTTP RESTful API 的定义，以此来规范 RESTful 服务开发过程。
OpenAPI 发展历程
在发展历程方面，OpenAPI的发展可以分为以下几个阶段：
起步阶段：2011年至2013年，这一阶段主要是API描述语言的提出和应用。
发展阶段：2013年至2016年，这一阶段主要是OpenAPI标准的制定和推广。
成熟阶段：2016年至今，这一阶段主要是OpenAPI的广泛应用和普及。
OpenAPI 规范
OpenAPI规范包括如下几点 ：
版本
开放API规范采用语义化版本控制2.0.0（semver）标准来命名版本号。
语义化版本的主版本号和次版本号（例如3.0）用于标识开放API规范中的功能变化。通常，修订号版本（如3.0.1）用于表示文档的错误修正而非功能更新。支持开放API规范3.0的工具应兼容所有3.0.x的版本，且不应区分修订版本号，例如对工具来说，3.0.0和3.0.1应当是等效的。
在相同主版本号下发布的更高次版本（如3.1.0）的开放API规范，不应干扰那些针对较低次版本（如3.0.0）开发的工具。因此，面向3.0.0规范开发的工具应能在3.1.0规范下正常工作。
任何兼容开放API规范3.x.x的文档都应包含一个openapi字段，以指明所使用的规范的语义化版本。
格式
遵循开放API规范的文档是一个自包含的JSON对象，可以采用JSON或YAML格式编写。
例如，表示一组值的字段在JSON格式下表示为：
{
"field": [1, 2, 3]
}规范中的所有字段名都应使用小写字母。
字段分为固定字段和模式字段两种。固定字段的名称是预定义的，而模式字段的名称需要遵循特定的模式。
如果一个对象中包含模式字段，则该对象中的模式字段名称不得重复。
为了保持在YAML和JSON格式之间的转换能力，建议使用1.2版本的YAML，并遵守以下限制：
- Tags必须符合JSON Schema ruleset所允许的范围。
- Keys必须是YAML Failsafe schema ruleset定义的纯字符串。
注意：尽管API文档使用YAML或JSON格式编写，但API的请求体和响应体或其他内容可以是任何格式。
文档结构
OpenAPI文档可以是单个文件，也可以拆分为多个文件，文件间的连接由用户自行决定。在拆分文件的情况下，必须使用$ref字段进行相互引用，如JSON Schema中所定义。
建议将根OpenAPI文档命名为openapi.json或openapi.yaml。
数据类型
在OAS中，原始数据类型基于JSON Schema Specification Wright Draft 00所支持的类型。注意，整数也作为一个支持的类型，并定义为不包含小数或指数部分的JSON数字。null不是一个支持的类型（有关替代方案，请参考nullable）。
模型使用Schema对象定义，这是JSON Schema Specification Wright Draft 00的一个扩展。
原始类型可以有一个可选的format属性。OAS使用多个已知格式来丰富类型定义。尽管如此，format属性被设计为一个开放的字符串属性值，可以包含任意值，例如”email”、”uuid”等未在此规范中定义的格式也可以使用。未定义的format属性类型应遵循JSON Schema中的类型定义。如果工具无法识别某个format值，应回退到type值，就像format未指定一样。
OAS定义的格式包括：
| 通用名 | 类型 | 格式 | 备注 |
|---|---|---|---|
| integer | integer | int32 | 32位有符号 |
| long | integer | int64 | 64位有符号 |
| float | number | float | |
| double | number | double | |
| string | string | ||
| byte | string | byte | base64编码的字节 |
| binary | string | binary | 任意8进制序列 |
| boolean | boolean | ||
| date | string | date | 定义于full-date – RFC3339 |
| dateTime | string | date-time | 定义于date-time – RFC3339 |
| password | string | password | 告知输入界面不应明文显示输入信息 |
富文本格式
整个规范中的description字段支持CommonMark markdown格式。OpenAPI相关工具至少需要支持渲染CommonMark 0.27中描述的富文本格式。出于安全考虑，相关工具可以选择忽略某些CommonMark特性。
URL的关联引用
除非另有规定，所有URL类型的属性值都可以是相对地址，如RFC3986中定义的那样，以Server对象作为Base URI。
在$ref中的相对引用基于JSON Reference，以当前文档的URL作为base URI。同时参考Reference对象。
OpenAPI 价值
1、使用 OAS 帮助激发需求：标准的文档化描述，有利于团队协同
2、使用OAS进行API设计：无论 API设计工具提供商使用什么工具和工件，OAS 都会提供设计过程的有形输出。拥有一个定义良好且可版本化的工件对于 API 生命周期后续步骤的准确性和效率至关重要。OpenAPI 文档（使用适当的机制进行源代码控制）允许以合理的方式实现这一点，并为开发提供清晰明确的输入。
3、使用 OAS 配置您的基础设施：API 管理可以说是这种情况下最常见的架构组件。其功能是保护 API 提供商的 API，并提供基于生命周期的功能，帮助组织无缝操作其 API。大多数 API 管理工具都支持使用 OpenAPI 文档作为配置的输入，例如，使用它来构建 API 网关配置，该配置观察 API 的结构并实现路径和参数验证、请求正文验证并提供对与 API 功能相关的安全系统的标注。
4、使用 OAS 进行API测试：API 测试是 OAS 大量投资工具作为输入的一个领域。例如，使用工具执行合同测试来检查设计和实现是否匹配是 API 提供商的常见活动。对于安全工具来说也是如此，它测试 API 足迹是否存在实现中的弱点。OpenAPI 文档提供了 API“应该”提供什么的定义，因此为可能无意暴露或实施薄弱安全实践的基线提供了基础。
API 生命周期中的 OAS
当人们考虑 API 生命周期时，就会开始清楚 OpenAPI 文档的有用性。考虑下面的简单 API 生命周期。它基于 API 优先的设计思想，无需编写任何实现代码即可设计接口。OAS 可以在此生命周期的每个阶段使用。
组织内的 API 生命周期显然比上述步骤有更多细微差别，并且无疑将针对使用中的软件开发生命周期进行定制。例如，敏捷方法可以多次迭代上面所示的步骤。然而，出于示例的目的，这种简化的视图有其优点，因为它显示了 OAS 在每个阶段的实用性。
OpenAPI 参考实现
Swagger设计工具是OpenAPI规范的基准实现，由多个组件组成，它是一个开源的构建工具，能够帮助开发人员设计，构建文档，测试接口，文档规范化，和消费掉Restful API。主要功能包括：
- Swagger Editor 是一个编辑工具，可以编辑描述API；
- Swagger UI 能让OpenAPI呈现出规范的可交互的API文档，以供他人查阅；
- Swagger Codegen 基于OpenAPI规范 能够生成客户端类库，服务端文档和存根，并且支持多语言，支持使用Docker,jar等方式运行构建；