昂首阔步的教程

Swagger是记录标准api的标准方法。在azure中部署api时，Swagger很有帮助。Swagger主要用于记录API;现在问题来了，为什么要记录api ?在企业内部或供公众使用的构建api，其主题与开发人员通常在他们正在构建的应用程序中使用的主题相同。为了让其他开发人员能够使用我们的API, API必须有适当的文档;否则，他们怎么知道API公开的端点是什么，以及这些端点上支持的操作是什么?它们应该传递什么参数?它们将返回什么参数?使用什么身份验证方法?为了回答这些问题，记录api是非常重要的; if you want APIs to be consumed and properly used.

Swagger和Open API规范是对API进行文档化的方法，说明了API究竟可以做什么。

什么是API?

API代表应用程序编程接口。它定义了两个软件如何相互通信。有几种类型的API，但是swagger专门处理Web API。

Web api是如何工作的?

让我们通过一个示例来理解如何使用Web API。假设我们打开脸谱网在我们的手机上向脸谱网服务器。请求发送到脸谱网服务器被称为API请求和脸谱网服务器将发送称为API响应的响应。服务器将只发送数据，而不是整个网页。显示网页是应用程序的责任。

这里，API定义工作:

哪些请求是可用的
每个请求的响应是什么样子的。

Swagger和Open API规范主要是为Rest API设计的，其中Rest是一种web API。在Rest word中，R代表Representational, S代表State, T代表Transfer。

什么是API定义?

API定义是一个文件，它描述了我们可以用API做的所有事情。它包含了我们可以向API发出的所有请求。它还描述了要发出什么请求以及每个请求的响应是什么样的。

为什么要创建API定义?

编写API定义有几个优点:

它允许您在实现API之前设计API。开发人员可以在为API编写代码之前检查API。
它还有助于自动化测试。
它可以自动创建多种语言的代码。
它还可以用于自动生成文档。

API定义文件

API定义文件是一个文件，它包含了你可以用一个文件做的所有事情。该文件包含以下内容:

服务器位置
如何处理安全性，即授权。
该API中所有可用的资源。
您可以在请求中发送的所有不同数据。
返回什么数据
什么HTTP状态码可以返回

请求剖析

在Http请求中可以找到五个不同的部分:

方法:方法描述要执行的操作。这些方法可以是POST、PUT、DELETE、GET。
URL:它指定要对其执行操作的名称。
查询参数
报头:报头用于存储有关请求的信息。
主体:主体包含附加数据。

URL被分成几个部分:

例如:请求URL为:https://api.example.com/v2/user

方案:https
主持人:api.example.com
基本路径:/v2
路径:用户

注意:API的主机和基本路径将保持相同，但路径根据请求而不同。

请求体

对于PUT、POST等方法，我们主要以JSON格式指定请求体。body被视为参数，就像url中的path一样。与这些参数不同，我们为请求体创建模式，指定JSON体的外观。

在REST中，响应体可以是任何东西，但主要是编写响应体JSON格式。响应体包含在响应对象中。响应体具有表示结构化数据的模式。我们还可以为每个对象使用单独的响应对象HTTP返回状态码。

安全

这里的“安全性”是指身份验证和授权。身份验证意味着通过用户名和密码验证用户。授权意味着允许用户访问数据。

可以通过以下方式设置安全性:

没有:在这里,没有一个意味着没有设置访问API的安全性。
基本认证:这意味着为每个请求设置用户名和密码。
API密匙:密钥设置为访问API。
誓言:它是一个授权方案。

文档

OAS文件或API文件包含自动生成文档的元素的人类可读描述。换句话说，我们可以说为API、为每个操作(路径和方法的组合)、为每个参数和每个响应元素添加了一个描述部分。

结构化数据格式

开放API规范将结构化数据格式用于其API定义文件。我们可以使用两种结构化格式中的一种，即YAML或JSON。

YAML

YAML代表不是标记语言。它不像超文本标记语言它用于数据，而不是用于内容。与JSON和JSON相比，YAML使用最少的字符XML．主要用于配置

而不是像JSON那样通过web传递的文件。

键/值对

YAML中的数据以键/值对的形式表示。键/值对由冒号后跟空格表示。

例如:

在上面的示例中，Date和First Name为键，2021-07-08和John为值。

水平

级别由空格缩进表示，但我们不能使用制表符缩进。这是YAML与其他结构化格式的最大区别。XML使用添加一层的标签，在标签内，还有其他添加另一层的标签;这样就增加了字符的数量。在JSON中，左括号和右括号表示一个级别占用许多字符。在YAML中，只使用缩进，它占用更少的字符。

XML:

JSON:

YAML

类型

YAML中的类型是从上下文确定的。

例如:

在上述场景中，part_no将被视为字符串，描述也会被视为字符串，价格将被视为浮动类型，而数量将被视为整数。

注意:在YAML中，我们不需要在字符串周围加上引号。有一个例外，如果某些东西被解释为数字或布尔值，则需要引号。

列表

YAML中的列表类似于JSON。我们需要使用破折号来表示列表项。
我们不需要申报清单。

            购物车:-part_no: A4786描述:光电阻器价格:1.47数量:4 -part_no: B3443描述:LED颜色:蓝色价格:0.29数量:12
           

正如我们在上面的例子中所看到的，cart是列表的名称，并且cart中有两个列表项。这两个列表项都用破折号表示。第一个列表项包含4个键值对，而第二个列表项包含5个键值对。

多行字符串

我们知道字符串不包含引号，所以我们需要多行字符串的特殊字符。以下是用于多行字符串的字符:

b|:它保留了行和空格。
它的意思是折线。

在上面的示例中，我们使用了'|'字符，因此它的输出将与上面所写的相同。

输出

YAML和JSON

如果我们使用>字符代替'|'字符:

S: > YAML和JSON。

输出

YAML和JSON

Swagger的历史

从历史上看，Swagger是一个关于如何创建API定义文件的规范。
当新版本(即Swagger 2.0)发布时，规范变成了开放API规范(OAS)。
现在，swagger不再是一个规范，而是使用开放API规范(Open API specification, OAS)的工具集合。
许多人把美洲国家组织称为Swagger，但从技术上讲，它不是。

开放API计划

开放API计划是由行业专家联盟创建的一个组织。
它专注于创建、发展和推广与供应商无关的API描述格式。
它负责开放API规范，但不负责任何使用它的工具。

在理解什么是swagger之前，我们首先要理解什么是Open API规范?

什么是开放API规范?

最初，它被命名为swagger规范，但后来它被重命名为Open API规范。Open API规范是一种规范，其中规范是一组规则，指定如何做某事。因此，开放API规范是一组描述如何用语言指定Restful API的规则。不管api使用的是什么技术，比如JAVA，PHP，net，或者其他什么东西，我们希望我们的API能够被他们正在构建的其他开发人员轻松地使用。为了正确理解API，我们应该了解API的以下所有内容:可用的端点(如/客户、/雇员、/订单等)是什么，每个端点(如GET、PUT、POST、DELETE等)上的可用操作是什么，API公开的每个端点上的可用操作是什么?传递什么参数及其数据类型?API的返回值和它的数据类型，使用的认证方法是什么?我们希望外部世界甚至内部客户端都能了解我们的API，而不必共享源代码。所以，一定有一些我们应该遵循的规则和标准来描述API，每个人都会遵循同样的规则，用同样的方式描述他们的API。在这里，开放Api规范的作用是简单地定义一组规则，这些规则指定如何描述Restful Api。它们有描述Restful服务各个方面的规则。有一些规则指定API上可用的端点。类似地，在每个端点上都有指定操作的规则，基本上每件事都有规则，例如，它们的参数、数据类型、返回值、身份验证方法等。 The open API specification can also be defined as a standard and language agnostic way to describe a Restful API. The idea is to create a document following these rules either in a JSON or YAML format that describes your entire API such as available endpoints, available operations, what parameters to pass, return value, their data types, and authentication methods.

让我们看看如何构建一个OAS文件。

我们将考虑一个示例，然后构建一个文件。假设公司名称是javatpoint.com, API服务正在上传和共享照片。这里，API基URL是https://api.javatpoint.com/photo

以启动文件为例。

            #每个开放API都包含这个Swagger: '2.0' #这是文档元数据info: version: "0.0.1" title: Photo Service host: api.javatpoint.com basepath: / Photo schemes: -https
           

在上述代码中，Open API规范在编写Open API规范之前调用swagger: 2.0。下一步是写文件本身，这是用一个键完成的“信息:”。在info项下，我们有版本绳子和标题的API。在title之后，API的主机是api.javatpoint.com，基本路径是/photo，因为url是api.javatpoint.com/photo。方案列表在这种情况下只有方案。

添加请求

让我们定义获取相册的请求。以下是会包括在申请书内的资料:

URL端点
HTTP方法
路径参数
查询参数

让我们通过一个示例来理解查询参数。

得到https://api.javatpoint.com/photo/album?start=2021-05-01&end=2021-05-31

API定义文件

            //端点路径:# photo album /album #获取一个或多个相册Get: #查询参数参数:#起始日期-name: start in:查询必选:false类型:字符串#结束日期-name: end in:查询必选:false类型:字符串
           

它以一个'paths'键开始，它是键的列表。换句话说，我们可以说这个url的操作列表在paths键中分组。这个键以'/album'开始，这意味着url以'/album'结束。返回一个或多个专辑的方法使用GET方法，因此我们将'/album'放在后面。get方法有一个参数列表。在上面的YAML中，list以'-'开头，因为API定义文件有一个查询参数列表。这个列表有关键:

名称:它是表示参数名称的键。
:它是将参数定义为基于查询的参数的键。
要求:在上面的例子中，这个键的值是false，这意味着它是一个可选字段。
类型:它是定义参数类型的键。

现在我们检索特定id的专辑。假设检索特定专辑的url如下所示:

得到https://api.javatpoint.com/photo/album/12345

上面的url将检索具有唯一id 12345的特定url。我们来看一下定义。

            # photo album/ album/{id}: #获取相册get: #查询参数参数:#相册id name: id in: path required: true类型:integer
           

在上面的YAML中，键定义为/专辑/ {id}在哪里id在大括号内定义。这表明稍后将用名称定义path参数“id”。然后，我们有一个get方法，然后我们包含了一个参数列表。这里我们只添加了一个名为“id”的列表项。'in'值是path，这意味着它是一个路径参数，'required'字段是true，在path参数中总是如此，类型是整数。

什么是图式?

某些类型的请求需要额外的数据，例如POST、PUT方法，这些方法被称为HTTP方法。包含这些方法的主体称为请求主体。请求体中包含的数据可以采用JSON或XML格式进行格式化。

响应体中表示的所有响应都可以格式化为JSON格式。在这里，模式主要定义数据的结构。OAS模式对象基于JSON模式规范。数据的模式决定键/值对中的键是什么，值是什么类型的数据。模式中可以有很多层次。

$ ref

$ref是一个特殊的OAS键，表示该值是对YAML文件中其他地方的结构的引用。它很有用，这样我们就不会在YAML文件中有那么多缩进级别。

让我们通过一个例子来理解。

File1:

File2:

在File1中，我们定义了a$ ref具有值的模式内的键“# /定义/ newAlbum”。我们已经创建了一个名为File2的文件，其中我们定义了一个名为“definitions”的新键，其中还有一个名为“newAlbum”的键，缩进结构反映在File1中的$ref key中。

请求体

方法下定义的参数参数关键。参数列表如下:

名称:它只是为参考而写的，但没有在文档中显示。
:它有'in'键，它被设置为body。
要求:它是通常设置为true的键。
模式:而不是类型，它有一个模式键，它有一个键$ref和$ref包含引用路径的值引号。

请求正文示例

上面的YAML有一个POST请求，其中包含参数键。参数有一个名为“album”的列表。它有一个模式，其中包含带有模式预期路径的$ref key。

模式部分

在模式部分，我们在文件末尾创建一个名为as definitions的键。
然后，我们添加一个关卡，并从$ref值中给它起一个名字。
添加属性键。
对于JSON中的每个top元素，添加其名称的键。
添加一个类型键，说明它是什么类型的键。
为其他数据添加其他键。

模式示例

在上面的模式中，我们可以观察到newAlbum有两个属性名为名字和目前为止,两者都是字符串类型。

注意:key/value的值不一定是简单类型;我们可以添加其他对象作为值。要做到这一点，我们需要遵循下面给出的步骤:

首先，我们需要使用对象类型。
然后，我们需要添加一个新的关卡属性:然后像之前一样继续

在上面的模式中，我们可以看到模式是对象的类型，后面跟着属性键。属性键有两个属性，分别命名为字符串类型的名字和姓氏。

上面的文件有很多缩进。为了克服这个问题，我们可以在定义中使用$ref。让我们通过一个例子来理解。

在上面的例子中，作者键具有$ ref的定义的路径人关键。这个人有属性键，该键具有两个名为第一个名字和姓。

模式的数组

我们也可以添加数组。
我们使用数组类型。
然后，我们添加一键项。
并定义类型和任何其他属性。

声明一个模式数组的语法是:

在上面的例子中，marks是包含字符串类型项的数组。

包含$ref的架构数组

对于复杂类型，使用$ref表示数组项。让我们通过一个例子来理解。

在上面的模式中，photos是array类型的键，并具有用于photo键路径的项列表。照片键有三个属性，即id类型为整数，经度类型为数字，纬度类型为数字。

斯威格是什么?

Swagger为开放API规范文件提供了一个编辑器。要访问swagger编辑器网站，请转到以下链接:

http://editor2.swagger.io

Swagger是用于生成交互式文档的流行工具之一。它为用户生成一个交互式API，以便他们能够更快地理解API。

Swagger和Open API规范之间的差异

OpenAPI是一种规范，而Swagger是用于实现该规范的工具。OpenAPI规范的开发是由OpenAPI计划完成的，该计划涉及来自世界不同地区的30多个组织。Smartbear软件公司是开发Swagger工具的公司，也是OpenAPI倡议的成员，因此它也帮助开发了该规范。

Swagger是一个与广泛使用的工具相关联的工具，用于实现OpenAPI规范。swagger工具集包括在API生命周期的不同阶段使用的开源、免费和商业工具。

以下是Swagger中包含的工具:

昂首阔步的编辑:它是一个工具，允许我们在浏览器内用YAML编辑Open API规范，还可以实时预览文档。
的界面:它是一个集合了HTML、Javascript和CSS资源的工具，允许我们动态地生成漂亮的文档。
昂首阔步Codegen:它允许我们自动生成API客户端库、服务器存根和文档。
昂首阔步的核心:它由与java相关的库组成，这些库用于创建、消费和使用API定义。
昂首阔步检查员:它是一个API测试工具，允许您验证API并从现有API生成OpenAPI定义。

Swagger文档

什么是自动生成文档?

像Swagger这样的工具获取OAS文件并从中生成HTML文档，这样就可以在web上进行更新。只要OAS文件保持最新，那么文档可能比手动编写文档更准确。它还允许您尝试文档中的请求，以便它可以帮助开发人员实现代码。

我们将使用Swagger编辑器设计和记录Restful API。

假设我们有一个学生API和资源，我们将根据Query参数从中获取学生姓名。在Query参数中，我们将传递学生姓名。在这个API中，我们还将使用POST操作在这个API的帮助下添加新的学生。我们还将执行GET操作，在path参数的帮助下检索数据。

在浏览器中打开Swagger编辑器，如下所示:

它是一个非常智能的工具，因为它提供了大量的建议。当我们按下ctrl + space,它为你提供了很多建议。

首先，我们使用openapi版本3.0.0如下所示:

现在我们将在元数据中添加API的基本信息，如下所示:

在上面，我们添加了API的标题、API的描述、API的联系方式等基本信息。

接下来我们必须添加服务器。我们可以通过添加每个服务器的url来添加多个服务器。

添加服务器之后，我们将添加路径。在路径内部，我们需要添加路径中的资源以及操作。

在上面，我们添加了学生资源及其描述。然后，我们包含了get操作。首先，我们提供的描述得到方法，然后我们包含我们将在Get方法中传递的参数。我们传递了名为的基于查询的参数Studentname下一个参数是必需的，为真studentname参数在Get方法中是必选的。现在我们将表示基于查询的参数的模式。在模式中，我们包含了参数的类型和示例。在本例中，我们指定了查询参数。

现在我们将指定下一级的响应。我们将首先提到响应:然后在响应中，我们需要指定显示响应的http代码。在实际场景中，我们应该涵盖所有主要响应代码。在这里，我们将指定满意的场景，即200个代码表示成功的响应。响应码后，我们将指定响应码的描述，成功的响应。然后，我们将指定内容的格式，即“application / json”表示内容将以json格式表示。一旦包含了内容的格式，我们就需要指定模式。由于这是响应，因此将执行get操作。操作的类型是数组，数组有一个项目列表，因此我们将这些项目指定为键。项目具有属性键。正如我们在上面的截图中看到的，它包含三个属性，即整数类型的Student id，字符串类型的Student name和Studentremarks字符串类型。

下一个操作是我们必须执行的POST操作。首先，我们将在编辑器中指定post方法，然后添加post方法“add a new Student”的描述。在POST方法中，我们需要指定requestBody正如它所期待的那样requestBody以JSON格式保存在学生对象中。在内容中，我们添加了内容的格式，即'application/json '。因为它是帖子操作，所以我们期望有对象类型而不是数组类型。的所有属性帖子操作和得到操作。添加完所有属性后，我们将添加响应键，在其中添加表示愉快场景的201代码。在响应键下，我们添加响应代码的描述，即:“记录已成功添加”。

到目前为止，我们正在使用查询参数获取学生资源。假设我们想用path参数获取学生资源，那么我们需要在路径中添加以下代码:

            /student{id}: description:根据路径检索student参数get: parameters: -in:路径名:id required: true schema:类型:integer responses: 200: description:成功响应，包含路径参数content: application/json
           

下面是完整的API定义文件:

            openapi: 3.0.0 info: title: Student API description: Student API by javaTpoint.com contact: name: javatpoint url: //m.047138.com version: 1.0.0 server: -url: http://devapi.com paths: / Student: description: Student资源get: description:获取Student数据的操作参数:- in:查询name: studentname required: true schema: type: string example: John responses: 200: description:成功Response content: application/json: schema: type: array items: properties:Student ID: type: integer example: 1 Student Name: type: string example: Peter Student备注:type: string example: High Grade Student post: description: Add a new Student requestBody: content: application/json: schema: type: object properties: Student ID: type: object properties: Student ID: type: integer example: 1 Student Name: type: string example: Peter Student备注:type: string example: High Grade Student responses: 201: description: Record successfully Add / Student {ID}: description:根据路径检索Student参数get: parameters: - in:路径name: id required: true schema: type: integer responses: 200: description:成功响应带有路径参数content: application/json: schema: type: array items: properties: Student id: type: integer example: 1 Student name: type: string example: Peter Student备注:type: string example: High Grade Student
           

输出