如何配置CentOS Swagger UI

一、准备工作

1. 更新系统：运行sudo yum update -y确保系统软件包为最新版本。
2. 安装必要工具：安装gcc-c++、make等编译工具（用于后续Node.js或Swagger依赖编译），命令：sudo yum install -y gcc-c++ make。

二、安装Node.js与npm Swagger UI依赖Node.js环境，需先安装：

1. 添加NodeSource官方仓库（以Node.js 14.x为例）：curl -sL https://rpm.nodesource.com/setup_14.x | sudo bash -。
2. 安装Node.js及npm：sudo yum install -y nodejs。
3. 验证安装：运行node -v（查看Node.js版本）、npm -v（查看npm版本），确认输出版本号即为成功。

三、安装Swagger UI 有两种常见方式，可根据需求选择：

方式1：通过源码包手动安装（适合自定义配置）

1. 下载Swagger UI源码：进入/opt/swagger目录，下载指定版本（如v3.34.0）的源码包：mkdir -p /opt/swagger && cd /opt/swagger && wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.34.0.tar.gz。
2. 解压源码包：tar -xzf v3.34.0.tar.gz。
3. 进入源码目录：cd swagger-ui-3.34.0。
4. 安装依赖：npm install。

方式2：通过Docker快速部署（适合简化流程）

1. 安装Docker：sudo yum install -y docker && sudo systemctl start docker && sudo systemctl enable docker。
2. 拉取Swagger UI镜像：docker pull swaggerapi/swagger-ui。
3. 运行容器：映射80端口到宿主机，docker run -p 80:80 -d swaggerapi/swagger-ui。

四、配置Swagger UI

若采用方式1（手动安装）：

1. 准备API文档：编写符合OpenAPI规范的JSON/YAML文件（如api.yaml），内容示例：

   openapi: '3.0.0'
   info:
     title: Sample API
     version: '1.0.0'
   paths:
     /hello:
       get:
         summary: Say hello
         responses:
           '200':
             description: Success
   

   将文件保存至/opt/swagger/swagger-ui-3.34.0/public目录。
2. 修改入口配置：编辑/opt/swagger/swagger-ui-3.34.0/public/index.html，找到url: "https://petstore.swagger.io/v2/swagger.json"，替换为本地API文档路径：url: "/api-docs/api.yaml"（若文档放在子目录需调整路径）。
3. 启动服务：进入源码目录，运行node index.js（若未创建index.js，可参考以下基础配置）：

   const express = require('express');
   const app = express();
   const path = require('path');
   app.use(express.static(path.join(__dirname, 'public')));
   app.listen(3000, () => console.log('Swagger UI running on port 3000'));
   

   保存为index.js，再运行node index.js。

若采用方式2（Docker部署）：

1. 修改API文档路径：若需使用自定义文档，运行容器时添加-e SWAGGER_FILE=/api-docs/api.yaml参数，并挂载文档目录：

   docker run -p 80:80 -v /opt/swagger/api.yaml:/api-docs/api.yaml -e SWAGGER_FILE=/api-docs/api.yaml -d swaggerapi/swagger-ui
   

   此时Swagger UI会自动加载/api-docs/api.yaml中的文档。

五、访问Swagger UI

• 若使用方式1手动安装：在浏览器输入http://<服务器IP>:3000（若修改了端口，替换为对应值）。
• 若使用方式2 Docker部署：在浏览器输入http://<服务器IP>即可访问。

六、生产环境优化建议

1. 启用HTTPS：使用Let’s Encrypt免费证书，通过Certbot配置Apache/Nginx的HTTPS监听，避免数据传输泄露。
2. 配置防火墙：开放对应端口（如3000、80、443），命令示例：sudo firewall-cmd --permanent --add-port=3000/tcp && sudo firewall-cmd --reload。
3. 权限管理：修改Swagger UI目录权限，避免敏感文件泄露：chmod -R 755 /opt/swagger。