centos swagger容器化方案

CentOS環境下Swagger容器化部署方案

一、基礎環境準備

在CentOS系統上部署Swagger容器前，需先安裝Docker（容器化運行環境）。執行以下命令完成安裝：

# 更新系統軟件包
sudo yum update -y
# 安裝Docker
sudo yum install -y docker
# 啟動Docker服務并設置開機自啟
sudo systemctl start docker
sudo systemctl enable docker

通過docker --version命令驗證Docker是否安裝成功。

二、使用官方鏡像快速部署Swagger UI

1. 拉取官方Swagger UI鏡像

Docker Hub提供了官方維護的Swagger UI鏡像（如swaggerapi/swagger-ui-express），可直接拉取使用：

docker pull swaggerapi/swagger-ui-express

2. 運行Swagger UI容器

通過docker run命令啟動容器，將容器的8080端口映射到主機的8080端口（可根據需求調整）：

docker run -d --name swagger-ui -p 8080:8080 swaggerapi/swagger-ui-express

• -d：后臺運行容器；
• --name swagger-ui：指定容器名稱為swagger-ui；
• -p 8080:8080：主機端口8080映射到容器端口8080。

3. 訪問Swagger UI

在瀏覽器中輸入http://<CentOS服務器IP>:8080，即可看到Swagger UI界面。默認情況下，Swagger UI會嘗試加載遠程API文檔（如petstore.swagger.io），后續可替換為自定義文檔。

三、自定義Swagger UI鏡像（適配特定需求）

若需要修改Swagger UI配置（如更換文檔路徑、添加認證、調整UI主題），可通過自定義Dockerfile構建鏡像。

1. 準備自定義文件

創建一個工作目錄（如swagger-ui-custom），并下載Swagger UI靜態文件（可從GitHub倉庫獲?。?/p>

mkdir swagger-ui-custom
cd swagger-ui-custom
# 下載Swagger UI靜態文件（以v3.50.0為例）
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.50.0.tar.gz
tar -xvf v3.50.0.tar.gz
mv swagger-ui-3.50.0/dist swagger-ui-dist

將自定義的swagger.json（或swagger.yaml）文件放入swagger-ui-dist目錄（用于定義API規范）。

2. 編寫Dockerfile

在工作目錄下創建Dockerfile，內容如下：

# 使用Node.js 14基礎鏡像（兼容Swagger UI 3.x及以上版本）
FROM node:14
# 設置工作目錄
WORKDIR /usr/src/app
# 復制Swagger UI靜態文件到容器
COPY ./swagger-ui-dist /usr/src/app/swagger-ui-dist
# 復制自定義Swagger配置文件（若有）
COPY ./swagger.json /usr/src/app/swagger.json
# 安裝Express和Swagger UI Express（用于托管靜態文件）
RUN npm install express swagger-ui-express
# 暴露端口
EXPOSE 8080
# 啟動Swagger UI服務
CMD ["node", "-e", "const express = require('express'); const swaggerUi = require('swagger-ui-express'); const app = express(); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(require('./swagger.json'))); app.listen(8080, () => console.log('Swagger UI running on port 8080'));"]

• COPY ./swagger.json /usr/src/app/swagger.json：將自定義的Swagger配置文件復制到容器；
• CMD：通過Node.js腳本啟動Swagger UI，并指定API文檔路徑為/api-docs。

3. 構建并運行自定義鏡像

# 構建鏡像（標簽為swagger-ui-custom）
docker build -t swagger-ui-custom .
# 運行容器（映射端口8080，掛載自定義配置目錄）
docker run -d --name swagger-ui-custom -p 8080:8080 -v /path/to/custom/swagger:/usr/src/app/swagger-ui-dist swagger-ui-custom

• -v /path/to/custom/swagger:/usr/src/app/swagger-ui-dist：將主機上的自定義Swagger目錄掛載到容器，方便動態更新文檔。

四、配置Swagger文檔路徑與訪問

若需讓Swagger UI加載特定的API文檔（如swagger.json），可通過環境變量或掛載卷實現：

• 環境變量方式（適用于官方鏡像）：

  docker run -d --name swagger-ui -p 8080:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui-express
  

  其中，-e SWAGGER_JSON=/foo/swagger.json指定文檔路徑，-v /bar:/foo將主機上的/bar目錄掛載到容器的/foo目錄。
• Dockerfile方式（適用于自定義鏡像）：
  在Dockerfile中通過CMD或ENTRYPOINT指定文檔路徑（如上述自定義Dockerfile中的require('./swagger.json')）。

五、兼容性與維護注意事項

1. 版本匹配：
   • Swagger UI版本需與OpenAPI規范版本一致（如Swagger UI 3.x及以上支持OpenAPI 3.0+，舊版2.x僅支持Swagger 2.0）；
   • Node.js版本需滿足Swagger工具要求（如Swagger UI 4.x需要Node.js 12+，舊版CentOS需通過nvm升級Node.js）。
2. 容器更新：
   定期拉取官方最新鏡像（docker pull swaggerapi/swagger-ui-express），停止并刪除舊容器（docker stop swagger-ui && docker rm swagger-ui），重新運行新容器。
3. 安全配置：
   • 生產環境中啟用HTTPS（可通過Nginx反向隧道或Docker的--ssl參數配置）；
   • 若后端為Spring Boot項目，需在SecurityConfig中為Swagger靜態資源（如/swagger-ui/**、/v3/api-docs/**）放行，避免404錯誤。