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仓库获取）：

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')）。

五、兼容性与维护注意事项

版本匹配：
- 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）。
容器更新：
定期拉取官方最新镜像（docker pull swaggerapi/swagger-ui-express），停止并删除旧容器（docker stop swagger-ui && docker rm swagger-ui），重新运行新容器。
安全配置：
- 生产环境中启用HTTPS（可通过Nginx反向隧道或Docker的--ssl参数配置）；
- 若后端为Spring Boot项目，需在SecurityConfig中为Swagger静态资源（如/swagger-ui/**、/v3/api-docs/**）放行，避免404错误。