OpenAPI概述是怎樣的

OpenAPI概述是怎樣的，針對這個問題，這篇文章詳細(xì)介紹了相對應(yīng)的分析和解答，希望可以幫助更多想解決這個問題的小伙伴找到更簡單易行的方法。

通常所說的OpenAPI是指OpenAPI規(guī)范（OpenAPI Specification），簡稱OAS，該規(guī)范用于規(guī)范RESTful風(fēng)格的API描述方法。

我們有很多種方法來描述一個web服務(wù)的API，比如使用world文件描述，但這樣的API描述不夠通用。 OpenAPI規(guī)范定義了一種通用的接口描述方法，按照這個規(guī)范定義接口，不僅適合人閱讀，也方便程序處理。

發(fā)展史

OpenAPI規(guī)范的前身是Swagger規(guī)范，其由名為Swagger API的項目發(fā)展而來。

2011年，美國的工程師Tony Tam創(chuàng)建了Swagger API項目，該項目由早期的規(guī)范和一系列工具組成，此時規(guī)范還稱為Swagger規(guī)范。

該項目最初幾年發(fā)展并不順利，只有一些小公司和個人開發(fā)者認(rèn)可該項目，同時業(yè)界也出現(xiàn)了一些競爭對手， 比如同樣用于描述API的RAML，雖然此時Swagger規(guī)范的熱度仍遠(yuǎn)遠(yuǎn)高于其競爭對手， 但這僅得益于Swagger API項目的先發(fā)優(yōu)勢。同期出現(xiàn)的競爭對手擁有強大的背景和資金支持，長期發(fā)展下去Swagger API項目必然落于下風(fēng)，進(jìn)而只能成為互聯(lián)網(wǎng)發(fā)展史上一個被人遺忘的詞條。

Swagger API項目若要繼續(xù)發(fā)展，不僅需要資金支持，還需要諸如Google這樣的互聯(lián)網(wǎng)大廠認(rèn)可，只有這樣Swagger規(guī)范才有可能成為業(yè)界通用的規(guī)范。

在2015年，Swagger API項目的創(chuàng)建者Tony Tam跳槽到了SmartBear Software公司，在該公司的支持下，Swagger API項目取得了奠定未來格局的變化。

同樣是2015年，SmartBear Software公司將Swagger規(guī)范捐獻(xiàn)給Linux基金會，Linux基金會專門成立新的項目OpenAPI Initiative用于托管該規(guī)范，新項目的創(chuàng)始成員包括Google、IBM和微軟等公司。通過該方式，Swagger規(guī)范得到了互聯(lián)網(wǎng)大廠的支持并得以繼續(xù)發(fā)展。

接著，Swagger規(guī)范從原Swagger API項目中剝離出來，更名為OpenAPI規(guī)范后托管到OpenAPI Initiative項目，Swagger API項目中仍保留了與該規(guī)范相關(guān)的工具。

自此，在Linux基金會的運作下，OpenAPI規(guī)范逐漸成為業(yè)界事實上的標(biāo)準(zhǔn)，而原Swagger API項目的資助者SmartBear Software公司則繼續(xù)運營與規(guī)范相關(guān)的工具產(chǎn)品，根據(jù)2017年的統(tǒng)計數(shù)據(jù)，這些工具每日下載量高達(dá)10萬次。

規(guī)范版本

當(dāng)SmartBear Software公司將Swagger規(guī)范捐獻(xiàn)給Linux基金會時，Swagger規(guī)范版本為2.0，業(yè)界習(xí)慣上將使用該規(guī)范描述的API文件命名為swagger.json，此時Swagger規(guī)范2.0版本和OpenAPI規(guī)范2.0版本是完全一致的，只是規(guī)范的一次重命名。

在Linux基金會的運作下，OpenAPI規(guī)范繼續(xù)演進(jìn)，并于2017年發(fā)布了3.0版本，該版本不僅支持使用JSON格式描述API還支持YAML格式，按照規(guī)范，使用該版本規(guī)范描述API的文件推薦命名為openapi.json或openapi.yaml。

schema

schema常被簡單地譯為模式，但它往往表示事物的組織和結(jié)構(gòu)，比如數(shù)據(jù)庫的schema表示數(shù)據(jù)庫的組織和結(jié)構(gòu)，同理OpenAPI規(guī)范也定義了一組schema對象，用于表示一個完整的OpenAPI規(guī)范文件。

每個版本的OpenAPI規(guī)范會有不同的schema對象，由于Kubernetes（v1.18.0）仍在使用OpenAPI規(guī)范2.0版本，所以本文僅介紹一點Kubernetes用到的schema對象，更詳細(xì)的內(nèi)容請查閱規(guī)范。

訪問kube-apiserver的/openapi/v2接口即可獲取完整的接口描述文件，比如在本地集群中執(zhí)行如下命令：

[root@ecs-d8b6 ~]# curl localhost:8080/openapi/v2

該命令會輸出完整的接口描述文件。該文件中由一系列字段組成，每個字段均稱為一個schema對象，字段分為必選字段和可選字段。

必選字段：swagger

swagger字段用于描述規(guī)范的版本，字段類型為string。比如Kubernetes的swagger字段如下所示：

{
	"swagger": "2.0",
	...
}

該字段表明當(dāng)前API文檔采用的規(guī)范版本，主要用于相關(guān)工具識別并處理該文檔。

必選字段：info

info字段用于描述API的基本信息，字段類型為Info Object。 Info Object類型包含以下兩個必須字段：

• title：類型為string，表示應(yīng)用的名稱。

• version：類型為string，表示應(yīng)用的版本。

比如，Kubernetes的info字段如下所示：

{
	"info": {
		"title": "Kubernetes",
		"version": "v1.19.0"
	},
	...
}

info字段表示了該文檔記錄的是Kubernetes的v1.19.0版本的接口。

必選字段：paths

paths字段用于描述API的各個端點及支持的操作，字段類型為Paths Object。 Paths Object類型又由Path Item Object類型構(gòu)成，Kubernetes的端點/api描述如下所示：

{
	"paths": {
		"/api/": {
			"get": {
				"description": "get available API versions",
				"consumes": [
					"application/json",
					"application/yaml",
					"application/vnd.kubernetes.protobuf"
				],
				"produces": [
					"application/json",
					"application/yaml",
					"application/vnd.kubernetes.protobuf"
				],
				"schemes": [
					"https"
				],
				"tags": [
					"core"
				],
				"operationId": "getCoreAPIVersions",
				"responses": {
					"200": {
						"description": "OK",
						"schema": {
							"$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions"
						}
					},
					"401": {
						"description": "Unauthorized"
					}
				}
			}
		},
		...
	}
}

從上面的信息可以看出端點（接口）/api/支持get操作，用consumes表示該接口支持的媒體類型，用produces表示該接口支持返回的媒體類型，用responses表示可能的返回值。

其中$ref表示引用自定義的另一個對象。

可選字段：definitions

definitions字段用于定義一組被各個接口引用（消費或產(chǎn)生）的對象，類型為Definitions Object。

{
	"definitions": {
		"io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions": {
			"description": "APIVersions lists the versions that are available, ...",
			"type": "object",
			"required": [
				"versions",
				"serverAddressByClientCIDRs"
			],
			"properties": {
				...
				"kind": {
					"description": "Kind is a string value representing the REST resource ...",
					"type": "string"
				},
				"serverAddressByClientCIDRs": {
					"description": "a map of client CIDR to server address that is serving this group. ...",
					"type": "array",
					"items": {
						"$ref": "#/definitions/io.k8s.apimachinery.pkg.apis.meta.v1.ServerAddressByClientCIDR"
					}
				},
				"versions": {
					"description": "versions are the api versions that are available.",
					"type": "array",
					"items": {
						"type": "string"
					}
				}
			},
			...
		},
		...
	}
}

簡單說來，使用definitions字段定義的字段可以被多個操作引用，從而達(dá)到復(fù)用的目的。需要引用其他對象時只需要使用$ref指定復(fù)用的對象即可，如下所示：

"$ref": "#/definitions/對象名"

在上面infos字段中引用了對象io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions用于表示接口調(diào)用成功后的返回內(nèi)容，該對象表示一定會返回versions和serverAddressByClientCIDRs信息，實際調(diào)用成功后的輸出如下所示：

[root@ecs-d8b6 ~]# curl localhost:8080/api/
{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "localhost:6443"
    }
  ]
}

關(guān)于OpenAPI概述是怎樣的問題的解答就分享到這里了，希望以上內(nèi)容可以對大家有一定的幫助，如果你還有很多疑惑沒有解開，可以關(guān)注億速云行業(yè)資訊頻道了解更多相關(guān)知識。