Swagger OpenAPI詳解

Swagger OpenAPI是一種RESTful API設計工具，可以用於創建和維護RESTful API文檔。它提供了一種簡單的方法來描述API，包括端點（endpoints）、HTTP方法（HTTP methods）、請求體（request body）和響應類型（response types）等元素。Swagger OpenAPI有助於製作易於使用、易於理解和易於瀏覽的API文檔，為API用戶提供了更好的體驗。

一、基本概念

Swagger OpenAPI可以用JSON或YAML格式來描述API。一個Swagger OpenAPI文檔包含API的完整信息，包括URL、HTTP方法、參數和返回類型。Swagger OpenAPI文檔使用以下關鍵字、構造和屬性：

swagger：Swagger OpenAPI規範的版本號。
info：包含API的元數據信息，如標題、描述、版本號和作者等。
host：API伺服器的主機名和埠。
basePath：API的公共基礎路徑。
schemes：API使用的協議（HTTP或HTTPS）列表。
paths：包含API的所有端點和操作信息。
parameters：定義可重複使用的參數模板。
responses：定義可重複使用的響應模板。
tags：用於對操作進行分組的標籤列表。

二、使用示例

以下是一個簡單的Swagger OpenAPI文檔示例：

swagger: '2.0'
info:
  title: Example API
  description: This is an example API documentation
  version: 1.0.0
  contact:
    name: John Doe
    email: john.doe@example.com
host: api.example.com
basePath: /v1
schemes:
  - https
paths:
  /users:
    get:
      tags:
        - Users
      summary: Get a list of all users
      parameters:
        - name: limit
          in: query
          description: Maximum number of users to return
          type: integer
          default: 25
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string
  /users/{id}:
    get:
      tags:
        - Users
      summary: Get a single user by ID
      parameters:
        - name: id
          in: path
          description: ID of the user to retrieve
          required: true
          type: integer
      responses:
        "200":
          description: Success
          schema:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string

上述示例展示了一個簡單的Swagger OpenAPI文檔，包含兩個端點：獲取所有用戶和獲取單個用戶。其中，/users端點支持GET請求，可以用limit參數指定返回用戶的數量。而/users/{id}端點支持GET請求，使用URL路徑參數{id}指定所要獲取用戶的ID。

三、SwaggerUI

SwaggerUI是一個基於Swagger規範生成互動式API文檔的工具。它可以讀取Swagger OpenAPI文檔，並將其轉換為易於理解的文檔界面。SwaggerUI不僅提供了API的詳細信息，還提供了API請求和響應的互動式控制器。SwaggerUI支持多種API語言，包括Java、Python、.NET和Node.js等。

在前面的示例中，SwaggerUI可以通過以下方式呈現：

<!DOCTYPE html>
<html>
  <head>
    <title>Example API</title>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.9.2/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.9.2/swagger-ui-bundle.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.9.2/swagger-ui-standalone-preset.js"></script>
    <script>
      window.onload = function() {
        SwaggerUIBundle({
          url: "/path/to/swagger.json",
          dom_id: "#swagger-ui",
          presets: [SwaggerUIBundle.presets.apis],
          plugins: [SwaggerUIBundle.plugins.DownloadUrl],
          layout: "StandaloneLayout"
        })
      }
    </script>
  </body>
</html>

上述示例中的url屬性是Swagger OpenAPI文檔的URL。當文檔載入完成並解析完畢後，SwaggerUI將根據文檔生成文檔界面，並允許用戶與API進行交互。SwaggerUI的默認主題很好看，但也支持自定義主題。

四、代碼生成

Swagger提供了許多代碼生成工具，可以根據API文檔自動生成客戶端和伺服器端代碼。這些工具可以使用各種編程語言生成代碼，如Java、Python、C#等。使用代碼生成工具可以節省許多時間和工作量，同時也可以幫助確保API的一致性和正確性。

以下是使用Swagger代碼生成工具生成Java客戶端代碼的示例：

swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l java -o petstore-client

上述示例中，-i參數指定Swagger OpenAPI文檔的URL，-l參數指定要生成的代碼語言，-o參數指定生成代碼的輸出路徑。以上命令將會生成一個Java客戶端代碼客戶端，並包括與petstore.swagger.io官方Petstore API的交互代碼。

五、結語

Swagger OpenAPI是一種優秀的API設計工具，可以幫助API開發者更加輕鬆地創建和維護RESTful API文檔。使用Swagger OpenAPI，你可以將API的目的、參數和返回類型等信息全部列在一起，在API的開發和使用過程中都有非常大的幫助作用。

原創文章，作者：小藍，如若轉載，請註明出處：https://www.506064.com/zh-tw/n/198323.html