什么是 OpenAPI 和 Swagger UI？

在開始之前，我們需要了解一些關鍵術語。

YAML

YAML 是一種人類可讀的標記語言，常用于配置文件。它的語法簡單且直觀，非常適合用來描述 API 的結構和行為。

Swagger UI

Swagger UI 是一個開源工具，可以將 OpenAPI 規范的文檔轉換為直觀的用戶界面。通過 Swagger UI，開發者可以交互式地測試 API，而無需編寫額外的客戶端代碼。

使用 Swagger UI 記錄 API 的兩種方法

使用 Swagger UI 記錄 API 通常有兩種方式：

1. 在代碼的每個端點上添加注釋

   Swagger UI 會解析這些注釋并生成一個直觀的用戶界面。

2. 使用獨立的 YAML 文件記錄端點

   將所有 API 文檔保存在與代碼分離的 YAML 文件中。這種方法更適合大型項目，也是本文的重點。

設置服務器以提供 Swagger UI 服務

在開始記錄 API 之前，我們需要設置服務器，使其能夠通過指定的路由（如 /docs）提供 Swagger UI 服務。

所需依賴

我們需要安裝以下兩個 Node.js 包：

1. swagger-ui-express：用于生成美觀的用戶界面。
2. yamljs：用于將 YAML 文件加載為 JavaScript 對象。

安裝命令如下：

npm install swagger-ui-express yamljs

配置 OpenAPI 文檔

以下是一個簡單的 OpenAPI 文檔示例，使用 YAML 格式描述：

openapi: 3.0.0
info:
  title: Express API With OpenAPI Docs
  description: A simple express REST API with OpenAPI docs generated by Swagger UI.
  version: 1.0.0
servers:
  - url: /

將上述內容保存為 api.yaml 文件，并在 Express 應用中加載它。

添加路徑和組件

在 YAML 文件中，我們需要定義 API 的路徑（paths），即端點的具體描述。這些路徑將記錄 API 的行為，例如請求方法、參數和響應格式。

為了避免重復，我們可以使用可重用的組件（components）。例如，定義常用的響應結構或參數模板，并在多個路徑中引用它們。

總結

通過本文的介紹，我們學習了如何使用 OpenAPI 和 Swagger UI 為 Express REST API 編寫文檔。使用 YAML 文件記錄 API 不僅使文檔更清晰，還能與代碼分離，便于維護和擴展。希望本文能夠幫助您更高效地記錄和管理 API 文檔。

原文鏈接: https://medium.com/@joshuaondieki/rest-api-docs-with-openapi-swagger-ui-de9cd7944c6