如何在Ubuntu上测试Swagger API

如何在Ubuntu上测试Swagger API

在Ubuntu上测试Swagger API可通过**交互式界面（Swagger UI）或自动化工具（如Newman、Dredd）**实现，以下是具体步骤：

一、准备工作：安装必要工具

测试前需安装Node.js、npm（Node.js包管理器）和Docker（可选，用于容器化部署）。

1. 安装Node.js和npm：
   更新系统包列表并安装：

   sudo apt update
   sudo apt install -y nodejs npm
   

2. （可选）安装Docker：
   若使用Docker运行Swagger UI，安装Docker.io：

   sudo apt update
   sudo apt install -y docker.io
   sudo systemctl start docker
   sudo systemctl enable docker
   

二、方法一：通过Swagger UI手动测试（最常用）

Swagger UI提供可视化界面，可直接发送请求并查看响应，适合手动验证接口功能。

1. 安装Swagger UI

• 选项1：通过npm全局安装

  sudo npm install -g swagger-ui-express
  

• 选项2：下载并解压Swagger UI
  从GitHub下载指定版本（如v3.48.0），解压后进入目录：

  wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
  tar -xvf v3.48.0.tar.gz
  cd swagger-ui-3.48.0
  

2. 配置Swagger UI

• 若使用npm安装：
  创建Express应用托管Swagger UI，新建server.js文件：

  const express = require('express');
      
  const swaggerUi = require('swagger-ui-express');
      
  const YAML = require('yamljs');
       // 解析YAML文件
  
  // 加载Swagger文档（需替换为你的文档路径）
  const swaggerDocument = YAML.load('./swagger.yaml');
      
  
  const app = express();
      
  // 托管Swagger UI，指定文档路径
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
      
  const PORT = 3000;
      
  app.listen(PORT, () =>
   console.log(`Swagger UI运行在 http://localhost:${
  PORT}
      /api-docs`));
      
  

  安装依赖并启动：

  npm install express swagger-ui-express yamljs
  node server.js
  

• 若使用下载的压缩包：
  进入解压后的目录，安装http-server并启动：

  npm install -g http-server
  http-server -p 8081
  

  此时Swagger UI会在http://localhost:8081运行。

3. 手动测试接口

• 打开浏览器访问Swagger UI（如http://localhost:3000/api-docs）。
• 在界面中找到目标接口，点击Try it out按钮。
• 输入必要参数（如路径参数、查询参数、请求体），点击Execute发送请求。
• 查看Response区域的结果（状态码、响应体、 headers等）。

三、方法二：通过自动化工具测试（适合CI/CD）

自动化测试可实现批量接口验证，适合集成到开发流程中。

1. 使用Newman（Postman CLI工具）

Newman可将Swagger文档转换为Postman集合，并执行自动化测试。

• 步骤1：导出Swagger文档为Postman Collection
  使用Swagger Editor或在线工具（如Swagger Converter）将swagger.yaml/swagger.json导出为Postman Collection JSON文件（如collection.json）。
• 步骤2：安装Newman：

  npm install -g newman
  

• 步骤3：运行测试：
  执行以下命令运行Collection：

  newman run collection.json -e environment.json --reporters cli,json
  

  其中environment.json为环境变量文件（如API基础URL），--reporters指定报告格式（命令行+JSON）。

2. 使用Dredd（针对OpenAPI的测试工具）

Dredd直接解析OpenAPI文档（YAML/JSON），生成并执行测试用例，验证接口是否符合文档定义。

• 步骤1：安装Dredd：

  npm install -g dredd
  

• 步骤2：运行测试：
  执行以下命令，指定OpenAPI文档和API基础URL：

  dredd swagger.yaml http://localhost:8080
  

  Dredd会自动比对文档与实际接口的响应，输出差异报告。

四、常见问题解决

• CORS问题：若API与Swagger UI不在同一域名下，需在API服务端启用CORS（如Spring Boot添加@CrossOrigin注解），或在Swagger UI配置中允许跨域。
• 认证问题：若API需要认证（如Bearer Token），在Swagger UI的“Authorize”按钮中输入Token，或在Newman命令中添加--auth参数。

以上方法覆盖了Ubuntu上Swagger API的手动与自动化测试需求，可根据场景选择合适的方式。

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