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

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

二、OpenAPI 規(guī)范

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

1、版本

開放openapi 規(guī)范采用語義化版本控制2.0.0（semver）標(biāo)準(zhǔn)來命名版本號(hào)。

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

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

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

2、格式

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

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

{

 "field": [1, 2, 3]

}

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

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

如果一個(gè)對(duì)象中包含模式字段，則該對(duì)象中的模式字段名稱不得重復(fù)。

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

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

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

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

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

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

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

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

模型使用Schema對(duì)象定義，這是JSON Schema Specification Wright Draft 00的一個(gè)擴(kuò)展。

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

OAS定義的格式包括：