Swagger Editor：完美的API文檔化利器

Swagger Editor是一款產生在完善RESTful API的時代下，由swagger.io發起的開源項目。它允許開發者使用簡潔的語法來編寫開放API的文檔，幫助你更快地將API的基本信息收集和定義成清晰的API文檔。

一、簡介與安裝

Swagger是一種API文檔化設計工具，提供了完全的RESTful API文檔化解決方案。而Swagger-ui則是一個針對Swagger的UI工具，提供了一個完全交互式工具樣式的API探索器，可以根據RESTful API描述文件所提供的API的基本信息自動生成API文檔，支持開發人員進行自助式、自控式的API探索、API測試。

Swagger Editor是Swagger的原型、設計與編輯工具，Swagger Editor提供了一個開放而又智能的編輯器，可以用來創建、編輯、審查、校驗、發布Swagger API文檔，它完全表達了Swagger API設計的途徑和架構。

Swagger Editor可以通過三種方式安裝：

1. 源代碼安裝

git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm run build

2. Docker安裝

# 從 Docker Hub 下載鏡像
docker pull swaggerapi/swagger-editor
# 運行容器
docker run -d -p 8888:8080 swaggerapi/swagger-editor

3. 部署在服務器上

下載最新版本的Swagger Editor，並將它部署到你的服務器上，啟動應用程序，這樣你的Swagger Editor就可以在服務器上訪問了。之後可以通過這個URL進行訪問：http://localhost:3333/。

二、Swagger Editor詳解

1. 定義API文檔信息

在Swagger Editor中定義API文檔的第一步就是提供文檔的元數據。以下是Swagger文檔中必填的元數據：

swagger: "2.0"
info:
  version: 1.0.0
  title: Sample API
  description: This is a sample API documentation

Swagger文檔的元數據用於定義API相關信息，例如版本號、標題和介紹等。版本號可用於跟蹤API的版本，並防止新的API版本對現有API的兼容性造成不利影響。標題和介紹則用於向用戶提供有關API的基本信息。除了必填元數據之外，Swagger API文檔還可以包含各種可選屬性。

2. 定義API路徑與操作

Swagger Editor的下一個步驟是為API定義路徑和操作。在Swagger中，每個路徑重定向到一個或多個操作。操作是實現API端點的方法之一。以下是一個API路徑和操作的定義示例：

paths:
  /user:
    get:
      summary: Retrieve a list of users
      description: Retrieves a list of users in the system
      responses:
        "200":
          description: A list of users was retrieved successfully
          schema:
            type: array
            items:
              $ref: "#/definitions/User"
      tags:
        - User
    post:
      summary: Create a new user
      description: Creates a new user in the system
      parameters:
        - name: user
          in: body
          required: true
          schema:
            $ref: "#/definitions/NewUser"
      responses:
        "200":
          description: A new user was created successfully
          schema:
            $ref: "#/definitions/User"
      tags:
        - User

在這個示例中，定義了一個路徑，該路徑響應對包含用戶列表的資源的GET請求，響應對創建新用戶的POST請求。對於每個URL，可以指定多個操作，這些操作對於響應不同的HTTP方法。每個操作都有一個可選的標籤，這使得在許多要素中對操作進行分類和組織非常方便。

3. 定義API模型

在Swagger中，模型是為API文檔定義結構的基礎。相應的，Swagger Editor可以通過編寫JSON模式來定義API模型。以下是定義數據模型的示例：

definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      username:
        type: string
  NewUser:
    type: object
    properties:
      username:
        type: string
      password:
        type: string

在這個示例中，定義了兩個模型：User和NewUser，分別表示保存有關用戶記錄的數據和創建新用戶的數據。每個模型都有一個類型和屬性。類型可以是JavaScript對象或它準備好的基本類型之一，如字符串、數字和Boolean。屬性描述了對象中保存的數據。屬性可以包括名稱、類型、格式、枚舉、默認值等

三、額外的用法

1. 在Swagger-UI中顯示API文檔

Swagger Editor不僅可以用來定義API文檔，還可以自動生成API文檔在Swagger-UI中進行輕鬆訪問。只需要在Swagger Editor中單擊”Generate Server”按鈕，即可將API定義轉換為HTML格式，在Swagger-UI中展示它們。

2. 與後端集成

Swagger Editor還支持與許多不同的後端Web服務框架集成。它們包括Express、Hapi、Sails等。這些框架中的集成使得使用Swagger Editor定義API變得更加容易，並提供了API測試和交互式文檔。

3. 自定義主題

Swagger Editor的UI十分簡潔，易於操作。如果你希望對UI進行個性化設置，Swagger Editor也提供一些自定義主題的選項。你可以使用CSS文件對Swagger UI進行專業化定製，包括修改文檔的字體、顏色、對比度等。

結語

使用Swagger Editor來定義、編寫和審查API文檔是一項相對簡單且重要的任務。其提供了一個完整的、可定製的工具箱，一些工具甚至還提供了API測試和交互式文檔。通過使用Swagger Editor提供的這些資源，開發者們可以更快捷地設計API並文檔化API，以便更廣泛地推廣和使用。