openapi（openapi官网）

本篇文章给大家谈谈openapi，以及openapi官网对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。

本文目录一览：

• 1、OpenAPI介绍-初步认识
• 2、API 入门（4）OpenAPI 文档结构
• 3、Swagger和OpenAPI

OpenAPI介绍-初步认识

OAS的优点：

我们再次来介绍下OAS，OpenAPI规范(OAS)是一种与供应商无关的基于http的远程api描述格式。它最初基于2015年SmartBear Software捐赠的Swagger 2.0规范。

总而言之，它就是用于定义和描述基于http或者基于类似http的远程api的一种规范。

整个OPENAPI的规范是很长的，对于新手来说是令人生畏的

所以我们需要先按主题、组织，简化浏览

OpenAPI文档是一个文本文件，一般是xxx.json或者xxx.yaml，是以json或者yaml格式来书写的

该文件被称为根文档并且可以被分割为多个json或者yaml文件 以让其更加清晰

一般来说，JSON不支持注释，需要:用逗号分隔字段，对象周围用花括号括起来，字符串周围用双引号括 起来，数组周围用方括号括起来。另一方面，YAML在数组项之前需要连字符，并且严重依赖缩进，这在大文件中可能很麻烦(在JSON中缩进完全是可选的)。YAML通常是首选的，因为它稍微减小了文件大小，但是这两种格式是完全可以互换的姿猜缓(只要使用YAML 1.2)。这些页面中的所有示例都将在YAML中给出。

然而，YAML是JSON的超集，这意味着这两种语法可以混合使用。虽然一般情况下不推荐这样做，但有时还是会派上用场的。例如

![p-images.jianshu.io/upload_images/26589460-1a456adb365a5a23.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

完全准确地说，OpenAPI文档就是一个完全符合OAS的单个JSON对象

这里有个站点可以以树形图的形式展示一个符合OAS的结构，可以用来帮助熟悉OAS规范

OpenAPI端点endpoints

api端点在OAS中就是上面刚刚提到的paths对象

paths:需要注意的是paths字段的值是个对象，而不是一个数组，其中每个字段的键是端点名字，值是一个 路径项对象，就像这样：

路径都必须以 / 开头，为什么paths对象要采用对象而不是数组，是因为这样可以更加明显地表示paths对象中的端点名称是唯一的

operation object操作对象，除了summary和description以外，操作对象一般来说还会描述操作的参数、载荷、可能的服务器响应等 paths:

/board:

response object响应对象，这里就是描兆贺述一个操作对象中具体的状态码对应的返回信息了,

这个对象中必须要有一个description，用于对该响应对象以及该状态码进行补充描述（本质上应该就是通用http状态码描述)

body of message:

上一步最后展示的是api端点中的响应对象，它位于操作对象中，实际上，在操作对象中除了description和responses以外，当然还有很多其他字段，比如还有request body object,跟响应对象相对应，它是请求对象。这里来介绍下在请求和响应对象中都会用到的一个字段： content，内容对象

content字段：它是标准媒体类型和OpenAPI媒体对象(OpenAPI Media Type Object)之间的映射对，比如:

responses: {

"200": {

"test/html": {OpenAPI媒体对象}

}

}

这意味着，可以根据不同的格式来返回内容

content:

application/json:

schema:

...

注意，对迹模于我们平时开发的json 格式的api来说的，一般content中的schema肯定都是object，因为我们都是返回一个对象，比如

这就是我们平时接口返回的一个典型例子，对于这种情况，我们应该将schema设置为object，然后再在object中进一步定义其下的各个字段

这里介绍各个数据类型的定义要求:

在schema对象中，通过type字段定义数据类型，type是一个字符串，可用的值为:number,string,boolean,array,object，根据type字段的值，会有一些配套的其他字段用于扩充定义

比如:对于string类型，就可以附加minLength和maxLength用于指定字符长度

对于integer类型，minimum和maximum字段可以用于指定最大最小值。

无论什么类型的值，都可以通过enum字段来限制该字段的值必须在它规定的范围内,enum是数组

对于数组类型，必须指定items字段，它也是一个schema对象，通过它来定义数组中的每个元素的类型。除此之外，数组的长度可以通过minItems和maxItems字段来指定

最后，对于对象类型的字段，必须通过properties字段来指定对象中的属性，properties是一个对象，其中的键是字段名，值是schema对象

parameters和requestBody

OAS提供了两种机制来指定输入数据，parameters和request body(消息体).parameters用于标识资源，request body用于提供资源的内容

每一个parameter对象描述一个参数，使用如下必须的字段：

额外的可选字段:

parameter type:

大多时候，指定参数的数据类型都是通过schema对象（也就是在parameter对象中的schema字段）来指定。schema对象允许定义原子或者复杂的数据类型（数组或者对象）

parameters:

在更高级的场景中，会通过content字段来指定字段类型，它提供一个单入口（媒体类型到OAS媒体类型的）的映射。注意：schema或者content二者必须存在其一。它们不能同时出现

request body object:请求体是通过在操作对象中的requestBody字段来指定的，唯一的必填字段就是content

components和$ref

复用描述，很常见的情况是文档太大以致于不好管理。为此我们可以通过复用机制来移除冗余的部分。

components对象:通过在根节点下的components字段定义，包含了要复用的对象的定义

当然，并非所有的对象都是可以复用的，只有那些作为components对象的字段才可以列出来，比如schemas,responses,parameters

引用对象：任意一个Components对象中的OpenAPI对象都可以通过引用对象来代替。

引用对象：通过 "$ref": "指向引用对象的uri资源路径"，来使用

servers对象提供了API的基础URL，通过servers字段来定义，它是一个数组，它可以存在于根节点、路径项对象或者操作对象中。

servers是一个数组，其中的每一个元素就是一个server对象，至少要有一个url字段，用于表示基础路径。一个可选的description字段，当不同层级都有指定servers时，只有层级最低的那一级会生效。例如:

API 入门（4）OpenAPI 文档结构

OpenAPI 文档能够使用机器可读的方式，描述类似基于 HTTP 协议的远程 API.

OpenAPI 文档实际上就野手是一个 JSON 对象，其中包含了在 OpenAPI 规范中定义的结构和字段。

OpenAPI 文档是一个文本文件，可以轮唤使用 JSON 格式或者 YAML 格式进行编写。

OpenAPI 文档的最小结构如下所示（YAML 格式）。

在任何 OpenAPI 文档中，文档的根对象都是 OpenAPI 对象。需要说明的是， openapi 和 info 两个颂桐嫌字段是强制要包含的；而且至少还需要包含 paths 、 components 和 webhooks 三个字段中的至少一个。在上面的示例中，我们选择了三个字段中的 paths 字段。示例中，字段说明如下：

我们用一张图可以更清楚地看到根对象和字段的关系：

Swagger和OpenAPI

OpenAPI Specification  (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API.

wagger  is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

OpenAPI同样提供swagger的浏览方式，且在spring boot项目中集成简单到哭，只在pom文件中加入：

  dependency

        groupIdorg.springdoc/groupId

     卖首  artifactIdspringdoc-openapi-ui/artifactId

       version1.2.32中陵数/version

/dependency

在配置文件中配置好访问路径，启动即可。与之对应，swagger要配置很多东西，且版本不断汪余更新，新版和旧版切换有调试成本。

openAPI 3.0集成： 

swagger 2.9.2 版本集成： 

[img]

关于openapi和openapi官网的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。