如何使用CentOS上的Swagger进行测试 - 问答

一、CentOS上Swagger测试前置准备

在CentOS系统上进行Swagger测试前，需完成以下环境配置：

更新系统：运行sudo yum update -y确保系统软件包为最新版本。

安装Node.js和npm：Swagger依赖Node.js环境，通过以下命令安装：

sudo yum install gcc-c++ make -y
curl -sL https://rpm.nodesource.com/setup_14.x | bash -  # 使用Node.js 14.x版本（兼容性更好）
sudo yum install nodejs -y
# 验证安装
node -v  # 应输出Node.js版本（如v14.xx.xx）
npm -v   # 应输出npm版本（如6.xx.xx）

安装Docker（可选，推荐用于快速部署）：若需通过Docker运行Swagger UI，需先安装Docker：
```
sudo yum install docker -y
sudo systemctl start docker
sudo systemctl enable docker
```

二、Swagger组件部署（两种方式）

1. 通过Docker快速部署（推荐）

Docker可简化Swagger UI的部署流程，无需手动配置依赖：

拉取Swagger UI镜像：

docker pull swaggerapi/swagger-ui:v4.15.5  # 拉取最新稳定版镜像

运行Swagger UI容器：
```
docker run -d -p 8080:8080 -e SWAGGER_FILE=/app/swagger.yaml -v /path/to/your/swagger.yaml:/app/swagger.yaml swaggerapi/swagger-ui:v4.15.5
```
其中：
- -p 8080:8080：将容器的8080端口映射到主机的8080端口；
- -e SWAGGER_FILE：指定Swagger文档路径（需替换为你的swagger.yaml/swagger.json文件路径）；
- -v：将主机上的Swagger文档挂载到容器内。
访问Swagger UI：在浏览器中输入http://<CentOS服务器IP>:8080，即可看到Swagger UI界面。

2. 手动部署（适用于自定义配置）

若需更多定制化功能，可手动下载并配置Swagger Editor和Swagger UI：

下载Swagger组件：

mkdir -p /opt/swagger
cd /opt/swagger
wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz
wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz
tar -xzf v3.14.0.tar.gz
tar -xzf v3.34.0.tar.gz

启动Swagger Editor：

cd /opt/swagger/swagger-editor-3.14.0
npm install -g http-server
http-server -p 8081  # 启动Editor服务，访问http://<IP>:8081编写API文档

启动Swagger UI：

cd /opt/swagger/swagger-ui-3.34.0
npm init -y
npm install express --save
mkdir public
cp -r dist/* public/  # 复制Swagger UI静态文件到public目录
# 编辑index.js（配置API文档路径）
vi index.js

在index.js中添加以下内容：

const express = require('express');
const app = express();
app.use('/static', express.static('public'));
app.get('/', (req, res) => {
  res.sendFile(__dirname + '/public/index.html');
});
app.listen(3000, () => console.log('Swagger UI running on port 3000'));

启动服务：node index.js，访问http://<IP>:3000即可看到Swagger UI界面。

三、编写/导入Swagger文档

编写Swagger文档：
使用Swagger Editor（http://<IP>:8081）编写API文档，支持YAML或JSON格式。例如，一个简单的swagger.yaml内容如下：

openapi: 3.0.0
info:
  title: Test API
  version: 1.0.0
paths:
  /user/query:
    get:
      summary: Query user information
      parameters:
        - name: userId
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

导入文档：
- 若使用Docker部署，在运行容器时通过-e SWAGGER_FILE指定文档路径；
- 若手动部署，将文档复制到Swagger UI的public目录（如/opt/swagger/public），并修改public/index.html中的SWAGGER_URL变量，指向本地文档（如http://<IP>:3000/static/your-swagger.yaml）。

四、使用Swagger UI进行接口测试

访问Swagger UI：打开浏览器，输入http://<CentOS服务器IP>:8080（Docker部署）或http://<IP>:3000（手动部署），进入Swagger UI界面。
查看接口列表：左侧面板会显示Swagger文档中的所有接口（如/user/query）。
测试接口：
- 点击目标接口（如/user/query），右侧面板会显示接口详情（参数、请求方式、响应格式）；
- 点击Try it out按钮，输入必填参数（如userId: 1）；
- 再次点击Execute，Swagger UI会自动发送HTTP请求到后端服务；
- 查看Response区域，显示后端返回的结果（如{"id":1,"name":"John"}）。

五、补充：使用curl命令测试接口

若需在终端中测试接口，可使用curl命令（无需依赖Swagger UI）：

GET请求（参数在URL中）：

curl "http://<服务器IP>:<接口端口>/user/query?userId=1"

POST请求（参数在Body中，表单格式）：

curl -X POST "http://<服务器IP>:<接口端口>/factory/insert" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "factoryName=TestFactory&no=123&remark=TestRemark"

POST请求（参数在Body中，JSON格式）：

curl -X POST "http://<服务器IP>:<接口端口>/material/selectAll" \
-H "Content-Type: application/json" \
-d '{"factory":"TestFactory","materialName":"TestMaterial","offset":0,"page":1}'

文件上传请求：

curl -X POST "http://<服务器IP>:<接口端口>/api/all/order/money" \
-F "file=@/path/to/local/file.xlsx" \
-F "startTime=2025-01-01" \
-F "endTime=2025-06-30"

注意事项

生产环境安全：测试完成后，建议禁用Swagger UI（如删除容器或停止服务），避免接口文档泄露；
防火墙设置：确保CentOS防火墙开放了Swagger UI的端口（如8080、3000），可通过firewall-cmd --add-port=8080/tcp --permanent和firewall-cmd --reload命令配置；
文档更新：修改Swagger文档后，需重启Swagger UI服务（手动部署）或重新挂载文档（Docker部署），确保界面显示最新内容。

0 赞

0 踩