在了解OpenAPI是什么之后，我們來了解下它的發(fā)展歷程，OpenAPI的發(fā)展可以分為以下幾個階段：

起步階段：2011年至2013年，這一階段主要是API描述語言的提出和應用。
發(fā)展階段：2013年至2016年，這一階段主要是OpenAPI標準的制定和推廣。
成熟階段：2016年至今，這一階段主要是OpenAPI的廣泛應用和普及。

二、OpenAPI 規(guī)范

openapi 規(guī)范包括如下幾點 ：

1、版本

開放openapi 規(guī)范采用語義化版本控制2.0.0（semver）標準來命名版本號。

語義化版本的主版本號和次版本號（例如3.0）用于標識開放API規(guī)范中的功能變化。通常，修訂號版本（如3.0.1）用于表示文檔的錯誤修正而非功能更新。支持開放API規(guī)范3.0的工具應兼容所有3.0.x的版本，且不應區(qū)分修訂版本號，例如對工具來說，3.0.0和3.0.1應當是等效的。

在相同主版本號下發(fā)布的更高次版本（如3.1.0）的開放openapi 規(guī)范，不應干擾那些針對較低次版本（如3.0.0）開發(fā)的工具。因此，面向3.0.0規(guī)范開發(fā)的工具應能在3.1.0規(guī)范下正常工作。

任何兼容開放openapi 規(guī)范3.x.x的文檔都應包含一個openapi字段，以指明所使用的規(guī)范的語義化版本。

2、格式

遵循開放openapi 規(guī)范的文檔是一個自包含的JSON對象，可以采用JSON或YAML格式編寫。

例如，表示一組值的字段在JSON格式下表示為：

{

 "field": [1, 2, 3]

}

規(guī)范中的所有字段名都應使用小寫字母。

字段分為固定字段和模式字段兩種。固定字段的名稱是預定義的，而模式字段的名稱需要遵循特定的模式。

如果一個對象中包含模式字段，則該對象中的模式字段名稱不得重復。

為了保持在YAML和JSON格式之間的轉(zhuǎn)換能力，建議使用1.2版本的YAML，并遵守以下限制：

• Tags必須符合JSON Schema ruleset所允許的范圍。
• Keys必須是YAML Failsafe schema ruleset定義的純字符串。

注意：盡管API文檔使用YAML或JSON格式編寫，但API的請求體和響應體或其他內(nèi)容可以是任何格式。

3、文檔結(jié)構(gòu)

OpenAPI文檔可以是單個文件，也可以拆分為多個文件，文件間的連接由用戶自行決定。在拆分文件的情況下，必須使用$ref字段進行相互引用，如JSON Schema中所定義。

建議將根OpenAPI文檔命名為openapi.json或openapi.yaml。

4、數(shù)據(jù)類型

在OAS中，原始數(shù)據(jù)類型基于JSON Schema Specification Wright Draft 00所支持的類型。注意，整數(shù)也作為一個支持的類型，并定義為不包含小數(shù)或指數(shù)部分的JSON數(shù)字。null不是一個支持的類型（有關(guān)替代方案，請參考nullable）。

模型使用Schema對象定義，這是JSON Schema Specification Wright Draft 00的一個擴展。

原始類型可以有一個可選的format屬性。OAS使用多個已知格式來豐富類型定義。盡管如此，format屬性被設計為一個開放的字符串屬性值，可以包含任意值，例如"email"、"uuid"等未在此規(guī)范中定義的格式也可以使用。未定義的format屬性類型應遵循JSON Schema中的類型定義。如果工具無法識別某個format值，應回退到type值，就像format未指定一樣。

OAS定義的格式包括：