189 8069 5689

OpenAPI概述是怎样的

OpenAPI概述是怎样的，针对这个问题，这篇文章详细介绍了相对应的分析和解答，希望可以帮助更多想解决这个问题的小伙伴找到更简单易行的方法。

坚守“ 做人真诚 · 做事靠谱 · 口碑至上 · 高效敬业 ”的价值观，专业网站建设服务10余年为成都门窗定制小微创业公司专业提供成都企业网站定制营销网站建设商城网站建设手机网站建设小程序网站建设网站改版，从内容策划、视觉设计、底层架构、网页布局、功能开发迭代于一体的高端网站建设服务。

通常所说的OpenAPI是指OpenAPI规范（OpenAPI Specification），简称OAS，该规范用于规范RESTful风格的API描述方法。

我们有很多种方法来描述一个web服务的API，比如使用world文件描述，但这样的API描述不够通用。 OpenAPI规范定义了一种通用的接口描述方法，按照这个规范定义接口，不仅适合人阅读，也方便程序处理。

发展史

OpenAPI规范的前身是Swagger规范，其由名为Swagger API的项目发展而来。

2011年，美国的工程师Tony Tam创建了Swagger API项目，该项目由早期的规范和一系列工具组成，此时规范还称为Swagger规范。

该项目最初几年发展并不顺利，只有一些小公司和个人开发者认可该项目，同时业界也出现了一些竞争对手， 比如同样用于描述API的RAML，虽然此时Swagger规范的热度仍远远高于其竞争对手， 但这仅得益于Swagger API项目的先发优势。同期出现的竞争对手拥有强大的背景和资金支持，长期发展下去Swagger API项目必然落于下风，进而只能成为互联网发展史上一个被人遗忘的词条。

Swagger API项目若要继续发展，不仅需要资金支持，还需要诸如Google这样的互联网大厂认可，只有这样Swagger规范才有可能成为业界通用的规范。

在2015年，Swagger API项目的创建者Tony Tam跳槽到了SmartBear Software公司，在该公司的支持下，Swagger API项目取得了奠定未来格局的变化。

同样是2015年，SmartBear Software公司将Swagger规范捐献给Linux基金会，Linux基金会专门成立新的项目OpenAPI Initiative用于托管该规范，新项目的创始成员包括Google、IBM和微软等公司。通过该方式，Swagger规范得到了互联网大厂的支持并得以继续发展。

接着，Swagger规范从原Swagger API项目中剥离出来，更名为OpenAPI规范后托管到OpenAPI Initiative项目，Swagger API项目中仍保留了与该规范相关的工具。

自此，在Linux基金会的运作下，OpenAPI规范逐渐成为业界事实上的标准，而原Swagger API项目的资助者SmartBear Software公司则继续运营与规范相关的工具产品，根据2017年的统计数据，这些工具每日下载量高达10万次。

规范版本

当SmartBear Software公司将Swagger规范捐献给Linux基金会时，Swagger规范版本为2.0，业界习惯上将使用该规范描述的API文件命名为swagger.json，此时Swagger规范2.0版本和OpenAPI规范2.0版本是完全一致的，只是规范的一次重命名。

在Linux基金会的运作下，OpenAPI规范继续演进，并于2017年发布了3.0版本，该版本不仅支持使用JSON格式描述API还支持YAML格式，按照规范，使用该版本规范描述API的文件推荐命名为openapi.json或openapi.yaml。

schema

schema常被简单地译为模式，但它往往表示事物的组织和结构，比如数据库的schema表示数据库的组织和结构，同理OpenAPI规范也定义了一组schema对象，用于表示一个完整的OpenAPI规范文件。

每个版本的OpenAPI规范会有不同的schema对象，由于Kubernetes（v1.18.0）仍在使用OpenAPI规范2.0版本，所以本文仅介绍一点Kubernetes用到的schema对象，更详细的内容请查阅规范。

访问kube-apiserver的/openapi/v2接口即可获取完整的接口描述文件，比如在本地集群中执行如下命令：

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

该命令会输出完整的接口描述文件。该文件中由一系列字段组成，每个字段均称为一个schema对象，字段分为必选字段和可选字段。

必选字段：swagger

swagger字段用于描述规范的版本，字段类型为string。比如Kubernetes的swagger字段如下所示：

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

该字段表明当前API文档采用的规范版本，主要用于相关工具识别并处理该文档。

必选字段：info

info字段用于描述API的基本信息，字段类型为Info Object。 Info Object类型包含以下两个必须字段：

  • title：类型为string，表示应用的名称。

  • version：类型为string，表示应用的版本。

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

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

info字段表示了该文档记录的是Kubernetes的v1.19.0版本的接口。

必选字段：paths

paths字段用于描述API的各个端点及支持的操作，字段类型为Paths Object。 Paths Object类型又由Path Item Object类型构成，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字段用于定义一组被各个接口引用（消费或产生）的对象，类型为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字段定义的字段可以被多个操作引用，从而达到复用的目的。需要引用其他对象时只需要使用$ref指定复用的对象即可，如下所示：

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

在上面infos字段中引用了对象io.k8s.apimachinery.pkg.apis.meta.v1.APIVersions用于表示接口调用成功后的返回内容，该对象表示一定会返回versions和serverAddressByClientCIDRs信息，实际调用成功后的输出如下所示：

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

关于OpenAPI概述是怎样的问题的解答就分享到这里了，希望以上内容可以对大家有一定的帮助，如果你还有很多疑惑没有解开，可以关注创新互联行业资讯频道了解更多相关知识。


当前文章：OpenAPI概述是怎样的
浏览路径：http://jkwzsj.com/article/gosiog.html

其他资讯