七桃资源网

七桃资源网

使用SWAGGER 2.0可以比以往更轻松地设计API

qtfan 0 49 次浏览 技术文章

(原文作者:Akila Amarasinghe)

正如我在上一篇博客(https://medium.com/@
akilaaroshana/open-api-initiative-and-future-of-api-space-with-the-open-api-specification-24b928d86f5a)答应的关于“开放API倡议和API空间与开放API规范的未来”，在这篇博客，我将解释如何设计一个完整的API与使用Swagger 2国际标准语言进行设计和记录API。对于Swagger的新手，我将对Swagger 2进行一些解释。

Swagger 2最初是由SmartBear Software推出的，后来他们将其捐赠给了Open API Initiative，该组织现在维护着这种世界标准的API定义语言。

在此博客内，我希望解释如何使用Swagger 2规范,设计一个简单的，但完整的API。我将尽力向每个人解释尽可能简单的解释。这就足够了，现在让我们开始设计一个API。

为了方便起见，我将本文分为9部分。

  1. Swagger 2.0概述
  2. 基本结构
  3. 元数据
  4. 基础地址
  5. 消费与生产
  6. 路径与操作
  7. 参数
  8. 响应
  9. 输入和输出数据Models

1. Swagger 2.0概述

在编写规范之前，最好先了解一下Swagger 2.0的结构概述。在这里，您可以以一种可以理解的方式看到Swagger 2.0的结构。您将了解它们的含义以及如何在本文的定义中编写这些部分。继续阅读。

2.基本结构

Swagger可以用JSON或YAML编写。在本文中，我将在YAML中进行解释。但是您也可以用JSON编写它。它们非常相似。如果您需要从YAML转换为JSON，或者反之亦然，请使用此在线工具(https://www.json2yaml.com/)。

我现在将解释Swagger 2.0规范的基本结构。制作完整的API需要此结构的所有部分。只有具备这些基本元素，您才能编写API。这是用Swagger 2.0编写的最基本的API规范。

现在，我将逐个元素地对此元素进行解释。这个基本结构包含列出的6个主要元素，swagger, info, host, basePath, schemes, paths。没有这些元素，我们就无法为API编写Swagger定义。所有这些元素对于编写完整的API规范都是必不可少的。

3.元数据

swagger：“ 2.0”元素说明这是Swagger 2.0。该元素的值必须为2.0。因此，此元素至关重要。

“ info：”元素说明标题，描述和版本。该元素对于规范来说是必不可少的元素，因为关于API的所有元数据都在本节中。

  • title：这是info元素中的必需元素。类型是“字符串”，它描述了应用程序的标题。
  • 描述：“字符串”的类型。包括有关应用程序的简短描述。
  • 版本：必填元素。“字符串”的类型。包括API版本。不是规范版本。

这些是“ info”元素的基本子元素。有关“ info”元素的更多子元素，请访问此处(https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#infoObject)。

4.基本网址

每个REST API路径都会附加一个URL。host，basePath和schemes元素描述了此URL的各个部分。定义中的路径实际上是相对于此URL的。例如，在上面的基本定义中，/ pets路径表示如下，

<scheme>://<host>/<basePath>/pets

这些元素用于以下目的：

scheme：这些是API使用的传输协议。Swagger 2.0支持http和https。

host：提供API的主机的域名或IP地址。

basePath：这是Swagger定义中定义的所有路径（将要讨论）的前缀，并且对于主机是相对的。这必须在Swagger定义中以斜杠定义。

这是一个例子

5.消费/生产

发出请求时，API会接受并返回数据。一些API调用仅接受数据，而某些同时接受和返回。Consumes和Produces元素定义API接受并返回的数据格式。这些称为MIME类型。这些MIME类型可以全局定义（API的根级别），也可以在本地为单个操作定义（将在“路径”部分中进行讨论）。

可以在Swagger 2.0定义中定义以下MIME类型。

这是JSON和XML类型的示例全局MIME类型定义。

6.路径与运作

“路径”元素在API规范中起着重要作用。在此元素内，我们可以定义API的资源或单个终结点以及用于这些终结点的HTTP方法。

可以在定义的全局路径部分中定义路径。请记住，所有这些路径都是相对于定义前面定义的basePath的。这是怎么发生的。

scheme::/host/basePath/path

这是在定义的“全局路径”部分中定义路径的方式。

正如我在第5节中提到的，我们可以像这样为特定的API在本地定义MIME类型，

您还可以定义“标签”，以所需的方式对API进行分组。为此，请在您定义的资源（此处为/cats ）下定义一个“ tags”元素，并提供所需的标签名称。

6.1路径模板

有时，路径是必需的参数。值可以是变量的地方。在这种情况下，Swagger 2.0中具有此功能，可以在路径中定义变量参数。

路径的可变部分可以用花括号定义，因此定义可以识别出它是指向数据集合的特定资源的可变参数。这里有些例子。

6.2操作

在定义中定义路径时，每个路径都需要相对的HTTP方法。Swagger 2.0支持以下HTTP方法。这些HTTP方法在Swagger中称为“操作”。

    • GET
    • POST
    • PUT
    • PATCH
    • DELETE
    • HEAD
    • OPTIONS

单个路径可以包含多个操作。Swagger将路径和HTTP方法的组合定义为唯一操作。这意味着您不能为同一路径定义两个GET方法或两个POST方法，即使它们具有不同的参数。

这是使用GET操作的简单路径。

这些操作支持一些可选元素，以用于记录。

  • summary : 有关操作的简短摘要
  • description：关于操作的详细描述（可以是多行的，也可以是GitHub风格的markdown）
  • tags：用于在swagger UI中对操作进行分组
  • externelDocs：允许引用其他外部文档

7.参数

Swagger中的参数在路径操作下的参数部分中定义。“ parameters”部分是一个数组，因此必须将其元素定义为数组。参数有几种类型，它们具有以下元素。

  • name：参数名称
  • type：参数类型（用于原始值参数）
  • schema：用于请求正文
  • description：关于参数的简短描述

这是使用path参数定义的路径。（将讨论参数类型）

7.1参数类型

参数类型根据参数的位置在Swagger中定义。这在“参数”部分下的元素“ in”中定义。这可以是“查询”或“路径”。

7.1.1查询参数

查询参数显示在URL的末尾，问号（？）后的名称名称对以＆符号分隔。这些可以是“必需的”，也可以不是“必需的”。

必需元素位于参数部分下，以指示该参数是否为请求所必需。“ required”键的值是布尔值。

例如： /cats?Id=123

7.1.2路径参数

请注意，“ in”键在查询和路径参数定义之间是如何变化的。使用path参数，我们可以将请求指向某个资源。path参数是必需的，因此您需要将必需的元素定义为true。该参数在一对大括号中指定。这是路径参数的简单示例。

例如： /cats/{catId}

8.回应

“响应”部分允许您定义不同的API期望的响应格式或类型。这是在“路径”元素下和参数定义（如果有）之后定义的。您还可以指定所需的响应代码作为特定API的响应。您还可以为响应添加简短说明。“ schema”关键字用于定义响应主体。

“模式”可以定义，

  • 基本类型（字符串或整数）
  • 数组类型的对象（带有JSON或YAML API）—在“ properties”元素下，您可以定义对象主体的元素。

这是一个示例响应元素，

响应主体也可以在“定义”部分中定义（将在“输入和输出模型”下进行讨论）。为此，我们必须在响应部分的“ schema”元素下使用“ $ ref”元素。通常，当在API定义中全局使用请求主体定义的响应主体时，将使用此“定义”部分。下面给出一个例子，

9.输入和输出模型

在“定义”部分中，可以定义API的响应主体和请求主体。……的定义。假设在上一节中定义“ Cat”定义时，使用上一节中讨论的“ schema”关键字下的“ $ ref”元素将定义的API的响应主体定向到“ definitions”部分中的“ Cat”定义。在“定义”部分，我们必须使用与响应部分相同的名称（即“猫”）。这是“猫”响应主体的定义，

总结一下，这是我们在此处设计的整个API定义，您可以通过查看并阅读我们根据所讨论的部分所应用的注释来获得更好的理解。

您可以使用Swagger编辑器(https://editor.swagger.io/)来验证您编写的定义。Swagger编辑器还可用于生成REST API客户端代码，供您在自己的应用程序中使用。

Swagger 2 API定义中可以包含许多其他内容。这是为您提供使用Swagger 2 API定义语言编写简单而完整的API定义的基本指南。内容取自Swagger官方网站，您随时可以在页面(https://swagger.io/)上找到更多内容。Swagger 3始终可用于设计具有新功能的API。您可以通过阅读本基础知识来使用Swagger 3规范设计API。设计API祝您好运。

如果您确实有帮助，请给我鼓掌。真的是这样 希望看到您的一篇新文章。:-)

原文:

https://medium.com/@akilaamarasinghe/design-apis-easier-than-ever-with-swagger-2-0-60a2ba696d7d

原文链接：，转发请注明来源！
七桃资源网 › 技术文章 › 使用SWAGGER 2.0可以比以往更轻松地设计API