如何测试ubuntu上的swagger API

如何在Ubuntu上测试Swagger API

在Ubuntu上测试Swagger API主要分为手动交互测试（通过Swagger UI）和自动化脚本测试（通过测试框架）两类，以下是详细步骤：

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

测试前需安装Node.js、npm（Node.js包管理器），这是运行Swagger UI及相关工具的基础：

sudo apt update
sudo apt install -y nodejs npm

验证安装是否成功：

nodejs -v  # 查看Node.js版本
npm -v     # 查看npm版本

二、手动测试：通过Swagger UI交互式测试

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

1. 安装并启动Swagger UI

方式1：通过npm安装Swagger UI
```
sudo npm install -g swagger-ui
```
启动服务：
```
swagger-ui
```
默认监听8080端口，访问http://localhost:8080即可进入Swagger UI界面。

方式2：使用Docker快速部署
若已安装Docker，可通过官方镜像快速启动：

sudo apt install -y docker.io  # 安装Docker
sudo docker pull swaggerapi/swagger-ui  # 拉取Swagger UI镜像
sudo docker run -d -p 8080:8080 swaggerapi/swagger-ui  # 运行容器

访问http://localhost:8080即可使用。

2. 导入API文档并测试

导入文档：
若API文档为swagger.yaml/swagger.json格式，可通过以下两种方式导入：
- 直接输入文档URL（如http://your-api-server/v2/api-docs）；
- 将文档文件拖拽至Swagger UI界面的“Drag and drop your Swagger YAML/JSON file here”区域。
  导入后，Swagger UI会自动解析文档并生成接口列表。
测试接口：
选择需要测试的接口（如GET /users），点击右侧的Try it out按钮；
若接口需要参数（如查询参数、请求体），在对应输入框中填写值；
点击Execute按钮，下方会显示API响应状态码（如200）、响应时间、响应体（如JSON格式的用户列表）。

三、自动化测试：通过脚本批量验证

若需要频繁测试或集成到CI/CD流程，可使用JavaScript+Mocha+Chai编写自动化测试脚本。

1. 安装测试依赖

sudo npm install -g mocha chai supertest yamljs express swagger-ui-express

mocha：测试框架，用于组织测试用例；
chai：断言库，用于验证响应结果；
supertest：HTTP请求库，用于模拟API调用；
yamljs：YAML解析库（若文档为YAML格式）；
express+swagger-ui-express：托管Swagger文档的Web服务。

2. 编写测试脚本

创建test-swagger.js文件，内容如下（以GET /users接口为例）：

const chai = require('chai');
const expect = chai.expect;
const request = require('supertest');
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

// 加载Swagger文档（假设为YAML格式）
const swaggerDocument = YAML.load('./api-docs.yaml');

// 创建Express应用并挂载Swagger UI
const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 编写测试用例：测试GET /users接口
describe('GET /users', () => {
  it('should return a list of users with status 200', (done) => {
    request(app)
      .get('/api-docs/users')  // 替换为你的API路径
      .expect(200)             // 预期状态码
      .end((err, res) => {
        if (err) return done(err);
        expect(res.body).to.be.an('array');  // 预期响应体为数组
        done();
      });
  });
});

3. 运行自动化测试

在终端执行以下命令：

mocha test-swagger.js

若测试通过，会显示✓标记及通过率；若失败，会输出错误信息（如状态码不符、响应体结构错误）。

四、常见问题解决

CORS问题：若API服务器未允许跨域请求，需在服务器端配置CORS（如Express中添加cors中间件）；
认证问题：若API需要认证（如Bearer Token），在Swagger UI的“Authorize”按钮中输入Token，或在自动化测试脚本的请求头中添加Authorization: Bearer <token>；
文档路径问题：确保Swagger UI能访问到API文档（如将文档放在项目根目录，或通过Nginx代理文档服务器）。

通过以上步骤，可在Ubuntu上完成Swagger API的手动交互测试与自动化脚本测试，满足不同场景的需求。