OpenAPI是什么 ？

能够向其他人（您的同事、合作伙伴或您提供 API 的组织）提供 API 定义对于开展业务至关重要。API 经济的成功取决于使用与 API 消费者相关的语言，反复、简洁和确定地执行此操作。

openapi 规范语言提供了执行此操作的标准化方法。您的 API 可以用不可知的术语进行描述，将它们与任何特定的编程语言解耦。API 规范的使用者不需要了解应用程序的内部结构，也不需要尝试学习 Lisp 或 Haskell（如果您选择用 Lisp 或 Haskell 来编写应用程序）。他们可以从您的openapi 规范中准确地理解他们需要什么，这些规范是用简单且富有表现力编写的语言。

那么OpenAPI是什么呢？OpenAPI 规范 (OAS) 正是实现了从 API 提供者到 API 消费者的知识转移。它是用于描述 API 的开放标准，允许您提供以 JSON 或 YAML 文档编码的 API 规范。它提供了全面的术语词典，反映了 API 领域中常见的概念，嵌入了 HTTP 和 JSON 的基础知识。当与支持工具结合使用时，它可以基于简单的文档提供丰富的体验。

openapi 规范使用规定的格式来描述 HTTP RESTful API 的定义，以此来规范 RESTful 服务开发过程。

## 一、OpenAPI 发展历程

在了解OpenAPI是什么之后，我们来了解下它的发展历程，OpenAPI的发展可以分为以下几个阶段：

起步阶段：2011年至2013年，这一阶段主要是API描述语言的提出和应用。
发展阶段：2013年至2016年，这一阶段主要是OpenAPI标准的制定和推广。
成熟阶段：2016年至今，这一阶段主要是OpenAPI的广泛应用和普及。

二、OpenAPI 规范

openapi 规范包括如下几点 ：

1、版本

开放openapi 规范采用语义化版本控制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）的开放openapi 规范，不应干扰那些针对较低次版本（如3.0.0）开发的工具。因此，面向3.0.0规范开发的工具应能在3.1.0规范下正常工作。

任何兼容开放openapi 规范3.x.x的文档都应包含一个openapi字段，以指明所使用的规范的语义化版本。

2、格式

遵循开放openapi 规范的文档是一个自包含的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的请求体和响应体或其他内容可以是任何格式。

3、文档结构

OpenAPI文档可以是单个文件，也可以拆分为多个文件，文件间的连接由用户自行决定。在拆分文件的情况下，必须使用$ref字段进行相互引用，如JSON Schema中所定义。

建议将根OpenAPI文档命名为openapi.json或openapi.yaml。

4、数据类型

在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定义的格式包括：