Swagger UI 中的第一个 API

Swagger UI 是一种开源工具，可为 OpenAPI 规范生成用户界面，允许用户可视化 API 端点并与之交互。该工具由 Swagger 项目开发和维护，该项目现在是更大的 OpenAPI Initiative 的一部分。

Swagger UI 可用于快速测试和探索 API，而无需额外的工具或软件。提供 OpenAPI 规范后，Swagger UI 会生成一个交互式文档页面，其中包含有关 API 端点、参数、响应等的信息。用户界面是根据规范中提供的信息动态生成的，这意味着对 API 所做的更改将自动反映在文档中。

除了提供文档和测试功能，Swagger UI 还支持语法高亮、响应验证和代码生成等多种功能。该工具可以与使用任何编程语言构建的 API 一起使用，并且可以进行自定义以匹配 API 的品牌和风格。

今天我们将在 Swagger UI 中添加我们的第一个 api。

服务器领域

在 OpenAPI 规范中，服务器对象用于定义有关托管 API 的服务器的信息。服务器对象包括几个字段，可用于提供服务器的 URL、协议和描述等信息。以下是可以包含在服务器对象中的字段：

url：此字段指定服务器的基本 URL。它是必填字段，必须包含在服务器对象中。

description：此字段提供服务器的描述。它是一个可选字段，可以包含以提供有关服务器的附加信息。

variables：该字段用于定义可以在url字段中使用的变量。变量括在大括号 ({}) 中，可用于表示可针对不同环境或用例自定义的 URL 部分。

scheme：此字段指定服务器使用的通信协议（例如 HTTP、HTTPS 等）。它是一个可选字段，如果未指定，则默认为“http”。

headers：此字段用于指定应包含在对服务器的请求中的任何标头。它是一个可选字段，可用于提供附加信息或身份验证凭据。

以下是包含所有字段的服务器对象示例：

"servers": [
  {
    "url": "https://api.example.com/{version}",
    "description": "Example API Server",
    "variables": {
      "version": {
        "enum": ["v1", "v2"],
        "default": "v1"
      }
    },
    "scheme": "https",
    "headers": {
      "X-API-Key": {
        "description": "API key",
        "required": true
      }
    }
  }
]

这是我们第一个 api 的服务器对象示例。 添加服务器。

标记字段

在 OpenAPI 规范中，标签对象用于为一组相关操作定义标签。标签对象包括几个字段，可用于提供标签名称、描述和相关操作等信息。以下是可以包含在标签对象中的字段：

name：此字段指定标签的名称。它是必填字段，必须包含在标签对象中。

description：此字段提供标签的描述。它是一个可选字段，可以包括在内以提供有关标签的附加信息。

externalDocs：此字段提供对标签的其他文档的参考。它是一个可选字段，可用于提供与标签相关的附加信息或资源。

x-tag-info：该字段是一个扩展字段，可用于提供有关标签的附加信息。它是一个可选字段，可用于提供有关标签的自定义信息或元数据。

以下是包含所有字段的标记对象的示例：

"tags": [
  {
    "name": "pets",
    "description": "Operations related to pets",
    "externalDocs": {
      "description": "Find more info here",
      "url": "https://example.com/pets/info"
    },
    "x-tag-info": {
      "owner": "John Smith"
    }
  }
]

这是我们第一个 api 的标记对象示例。 添加标签。

架构领域

在 OpenAPI 规范中，Schema Object 用于描述对象的结构和数据类型。架构对象包括几个字段，可用于提供架构类型、格式和属性等信息。以下是可以包含在架构对象中的字段：

title：此字段指定架构的标题。它是一个可选字段，可以包括在内以为模式提供人类可读的标题。

type：此字段指定模式的类型。它是必填字段，可以是多个可能值之一，例如“字符串”、“数字”、“整数”、“布尔值”、“数组”或“对象”。

format：此字段指定架构的格式。它是一个可选字段，可用于进一步指定模式的数据类型。例如，如果类型是“字符串”，则可以使用格式字段来指示该字符串是日期或时间。

description：此字段提供模式的描述。它是一个可选字段，可以包含以提供有关模式的附加信息。

properties：此字段指定对象模式的属性。它是一个可选字段，可用于定义对象属性的属性和数据类型。

items：此字段指定数组中项目的架构。它是一个可选字段，可用于定义数组项的数据类型。

required：此字段指定对象模式的必需属性。它是一个可选字段，可用于指定对象模式的哪些属性是必需的。

example：此字段提供架构示例。它是一个可选字段，可用于为架构提供示例值。

以下是包含所有字段的架构对象示例：

{
  "type": "object",
  "title": "Person",
  "description": "A person schema",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "John Smith",
    "age": 30,
    "email": "john.smith@example.com"
  }
}

这是我们第一个 api 的模式对象示例。 添加架构。

路径字段

在 OpenAPI 规范中，路径对象用于定义可用端点（或路由）和这些端点上的操作。路径对象是一个键值映射，其中键是端点路径，值是路径项对象。以下是可以包含在路径项对象中的字段：

HTTP方法：有几种HTTP方法，例如GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS和TRACE。此字段指定端点支持的 HTTP 方法。

summary：此字段提供端点操作的简要摘要。

description：该字段提供端点操作的详细描述。

parameters：此字段指定端点操作接受的参数。它可以是参数对象数组或对参数定义的引用。

requestBody：此字段指定端点操作期望的请求正文。它是一个可选字段，可以是 RequestBody 对象或对请求主体定义的引用。

responses：此字段指定端点操作可以返回的可能响应。它是一个键值映射，其中键是 HTTP 状态代码，值是响应对象。

callbacks：此字段指定与父操作相关的可能回调的映射。映射中的每个值都是一个回调对象。

deprecated：此字段指示端点操作是否已弃用且不应使用。

下面是一个包含所有这些字段的路径项对象示例：

{
  "/pets": {
    "get": {
      "summary": "Get a list of pets",
      "description": "Returns a list of pets that are available for adoption.",
      "parameters": [
        {
          "name": "limit",
          "in": "query",
          "description": "The maximum number of pets to return.",
          "required": false,
          "schema": {
            "type": "integer"
          }
        }
      ],
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        },
        "400": {
          "description": "Invalid input."
        },
        "401": {
          "description": "Unauthorized."
        },
        "500": {
          "description": "Server error."
        }
      }
    }
  }
}

这是我们第一个 api 的路径对象示例。 添加路径。

Swagger UI 可用于快速测试

这Try it out Swagger UI 中的功能允许用户通过发送请求和接收响应与 API 进行交互。它提供了一个用于测试 API 的用户界面，而无需编写代码或使用单独的工具。

当您单击Try it out 在 Swagger UI 中 API 操作旁边的按钮，您可以输入操作参数的值并向 API 发送请求。 Swagger UI 然后将显示 API 返回的响应。这使您可以快速测试和验证 API 的行为，而无需离开 Swagger UI 界面。

这Try it out 功能还可以帮助您探索 API 的功能并了解如何有效地使用它。通过与 API 实时交互，您可以看到它如何响应不同的请求，并了解有关它返回的数据的更多信息。

这是一个例子Try it out 对于我们的第一个 api。 Try it out