如何在Ubuntu上测试Swagger API

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

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

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

安装Node.js和npm：
更新系统包列表并安装：
```
sudo apt update
sudo apt install -y nodejs npm
```

（可选）安装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的手动与自动化测试需求，可根据场景选择合适的方式。

0 赞

0 踩