Swagger 是一個開放源代碼工具，主要用於設計、生成和記錄 API。它支援 OpenAPI 規範，這是一個標準化的 API 說明格式，用來描述 RESTful API 的結構。

下面是使用 Swagger 設計一個簡單 API 的基本步驟。

1. 安裝 Swagger 工具

首先，你需要在本地安裝 Swagger 工具。如果你使用 Swagger Editor，可以直接在線上進行編輯，無需安裝任何軟件。打開 Swagger Editor 即可開始編寫。

2. API 結構

假設我們要設計一個簡單的「任務管理 API」，可以進行以下操作：

主要功能：

• 列出所有任務
• 添加新任務
• 更新任務狀態
• 刪除任務

3. 使用 OpenAPI 規範編寫 API 定義

以下是一個簡單的 API 定義範例，使用 YAML 格式來描述。

openapi: 3.0.0
info:
  title: Task Management API
  description: An API to manage tasks.
  version: 1.0.0
servers:
  - url: http://localhost:8080/api
    description: Local server

paths:
  /tasks:
    get:
      summary: Get all tasks
      responses:
        '200':
          description: A list of tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    post:
      summary: Create a new task
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewTask'
      responses:
        '201':
          description: Task created

  /tasks/{taskId}:
    get:
      summary: Get task by ID
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A task by ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found
    put:
      summary: Update task status
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTask'
      responses:
        '200':
          description: Task updated
        '404':
          description: Task not found
    delete:
      summary: Delete task by ID
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Task deleted
        '404':
          description: Task not found

components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - pending
            - completed
    NewTask:
      type: object
      required:
        - title
      properties:
        title:
          type: string
        description:
          type: string
    UpdateTask:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - pending
            - completed

4. API 說明

• GET /tasks: 獲取所有任務。
• POST /tasks: 創建一個新任務，提供標題和描述。
• GET /tasks/{taskId}: 根據任務 ID 獲取特定任務。
• PUT /tasks/{taskId}: 更新指定任務的狀態（pending 或 completed）。
• DELETE /tasks/{taskId}: 刪除指定任務。

5. 測試 API

在編輯器中，你可以使用 Swagger 提供的 UI 界面直接進行 API 測試。當你完成設計後，可以導出 OpenAPI 規範，並將其應用到你的後端服務中。