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

一、CentOS上Swagger测试前置准备

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

1. 更新系统：运行sudo yum update -y确保系统软件包为最新版本。
2. 安装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）
   

3. 安装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文档

1. 编写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
   

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

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

1. 访问Swagger UI：打开浏览器，输入http://< CentOS服务器IP> :8080（Docker部署）或http://< IP> :3000（手动部署），进入Swagger UI界面。
2. 查看接口列表：左侧面板会显示Swagger文档中的所有接口（如/user/query）。
3. 测试接口：
   • 点击目标接口（如/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部署），确保界面显示最新内容。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！