建立私有 Swagger UI 服務

2026-11-02 約 880 字預計閱讀 2 分鐘

想必常使用 RESTful API 進行開發的人，對於好看、好讀的 API 文件都有一定的需求，而 Swagger 就是常見的工具之一。

什麼？你說你不知道這是什麼？相信你多少看過這個經典的 petstore.swagger.io API 文件。本文就來梳理如何在自己的環境中架設 Swagger UI，用容器運行非常簡單。這裡使用 swaggerapi/swagger-generator 映像內附的 Swagger UI 來示範。

Q: 為什麼我需要在家裡建一個 Swagger UI Server？

petstore.swagger.io 是一個放在外網 Internet 上的服務，供大家在線上使用。Swagger UI 會讀取指定網址的 OpenAPI Spec（JSON 或 YAML），將其中的 API 定義呈現為互動式文件，而不是掃描 API Endpoints 自動產生規格。

企業服務多半位於內網 Intranet，自行部署 Swagger UI 可以減少對外部網站的依賴。不過，規格文件與「Try it out」的 API 請求通常由使用者的瀏覽器發出，因此瀏覽器仍須能連到對應網址。

環境介紹

OS: Red Hat Enterprise Linux 9.6
Container Runtime: Podman 5.4
Swagger Generator: 2.4.53

以下指令以 root 身分執行。

安裝步驟

Firewall 開通

先確認提供服務的網卡所屬的 zone：

1
firewall-cmd --get-active-zones

以下假設該網卡位於 public zone；如果不同，請將下方的 public 換成實際的 zone。

1
2
3
4
firewall-cmd --zone=public --list-all
firewall-cmd --zone=public --add-port=80/tcp --permanent
firewall-cmd --reload
firewall-cmd --zone=public --query-port=80/tcp

這邊是開啟 host 上的 80 port，也可以選擇其他 port，請自行調整。

確認版本及下載 Swagger Generator

以下假設 Generator 部署在 http://swagger.misc.internal。GENERATOR_HOST 請設為 Generator 首頁的實際對外網址，讓內建 API 文件使用正確的服務位址。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 採用 Skopeo 來檢查可用標籤，本文使用固定標籤 v2.4.53
dnf install -y podman skopeo jq
skopeo list-tags docker://docker.io/swaggerapi/swagger-generator | jq -r '.Tags[]'

# 下載 Container Image - swaggerapi/swagger-generator:v2.4.53
podman pull docker.io/swaggerapi/swagger-generator:v2.4.53

# 執行
podman run --rm -d \
    -e GENERATOR_HOST=http://swagger.misc.internal \
    -p 80:8080 \
    docker.io/swaggerapi/swagger-generator:v2.4.53

# 打開你的瀏覽器 http://swagger.misc.internal

初次開啟會顯示 Swagger Generator 自身的 API 文件。這裡以 Quay 為例，改為載入它提供的 OpenAPI 規格文件：

在頁面上方的網址欄輸入 http://quay.misc.internal/api/v1/discovery。
按下 Explore，載入 Quay 的 API 文件。

要查看其他服務，將上面的網址換成使用者瀏覽器可存取的 OpenAPI JSON 或 YAML 網址即可。

如果各位比較習慣用 docker，也可以自行將 podman 置換成 docker 指令。

--rm 會在容器結束後自動移除容器，但下載的映像仍會保留；-d 只代表在背景執行，不會設定開機啟動。如果想讓服務開機啟動，可以參考 Podman Quadlet，交由 systemd 管理。

目錄