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