一、Swagger UI 简介
Swagger UI 是一个强大的工具，它能把 API 文档以可视化的界面展示出来，让开发者可以直接在界面上对 API 进行测试。它就像是一个桥梁，连接了 API 开发者和使用者，让大家不用写代码就能轻松测试 API。
1.1 优势
- 直观：界面友好，能清晰展示 API 的各种信息，包括请求方法、参数、响应格式等。
- 便捷：无需编写额外的测试代码，直接在界面上操作就能完成 API 测试。
- 文档性强：自动生成的 API 文档，方便团队成员之间的沟通和协作。
1.2 应用场景
- 开发阶段：开发者可以在开发过程中实时测试 API，及时发现问题并进行调整。
- 测试阶段：测试人员可以使用 Swagger UI 对 API 进行功能测试，确保 API 符合需求。
- 对外发布：可以将 Swagger UI 提供给外部合作伙伴，方便他们了解和使用 API。
二、处理复杂参数
2.1 复杂参数类型
在 API 测试中，复杂参数常见的有数组、对象等。下面以一个简单的 Node.js 项目为例，来看看如何处理这些复杂参数。
技术栈：Node.js + Express + Swagger UI
// 引入必要的模块
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
// 定义 Swagger 配置
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'API 测试',
version: '1.0.0',
},
},
apis: ['./routes/*.js'], // 指定 API 路由文件的路径
};
const specs = swaggerJsdoc(options);
// 使用 Swagger UI 中间件
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
// 启动服务器
const port = 3000;
app.listen(port, () => {
console.log(`Server is running on port ${port}`);
});
2.1.1 数组参数
假设我们有一个 API 接口，需要接收一个数组作为参数，用于查询多个用户的信息。
// routes/users.js
const express = require('express');
const router = express.Router();
/**
* @swagger
* /users:
* get:
* summary: 获取多个用户信息
* tags: [Users]
* parameters:
* - in: query
* name: userIds
* schema:
* type: array
* items:
* type: integer
* description: 用户 ID 数组
* responses:
* 200:
* description: 成功获取用户信息
*/
router.get('/users', (req, res) => {
const userIds = req.query.userIds;
// 这里可以根据 userIds 查询用户信息
res.send(`获取用户信息，用户 ID 为：${userIds}`);
});
module.exports = router;
在 Swagger UI 中，我们可以这样输入数组参数：在 userIds 参数的输入框中，输入多个整数，用逗号分隔，如 1,2,3。
2.1.2 对象参数
如果 API 接口需要接收一个对象作为参数，例如创建一个用户，需要用户的姓名、年龄等信息。
// routes/users.js
/**
* @swagger
* /users:
* post:
* summary: 创建用户
* tags: [Users]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* age:
* type: integer
* responses:
* 201:
* description: 用户创建成功
*/
router.post('/users', (req, res) => {
const user = req.body;
// 这里可以将用户信息保存到数据库
res.status(201).send(`用户 ${user.name} 创建成功`);
});
在 Swagger UI 中，我们可以在请求体输入框中输入 JSON 格式的对象，例如：
{
"name": "张三",
"age": 25
}
2.2 嵌套参数
有时候，参数会有嵌套结构，比如一个订单对象，包含订单信息和商品列表。
// routes/orders.js
const express = require('express');
const router = express.Router();
/**
* @swagger
* /orders:
* post:
* summary: 创建订单
* tags: [Orders]
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* orderInfo:
* type: object
* properties:
* orderNumber:
* type: string
* orderDate:
* type: string
* products:
* type: array
* items:
* type: object
* properties:
* productName:
* type: string
* price:
* type: number
* responses:
* 201:
* description: 订单创建成功
*/
router.post('/orders', (req, res) => {
const order = req.body;
// 这里可以将订单信息保存到数据库
res.status(201).send(`订单 ${order.orderInfo.orderNumber} 创建成功`);
});
module.exports = router;
在 Swagger UI 中，我们可以输入如下 JSON 格式的请求体：
{
"orderInfo": {
"orderNumber": "2023001",
"orderDate": "2023-10-01"
},
"products": [
{
"productName": "手机",
"price": 5000
},
{
"productName": "电脑",
"price": 8000
}
]
}
三、请求头设置
3.1 常见请求头
在 API 测试中，常见的请求头有 Authorization（用于身份验证）、Content-Type（指定请求体的格式）等。下面我们来看看如何在 Swagger UI 中设置这些请求头。
3.1.1 设置 Authorization 请求头
假设我们的 API 需要进行身份验证，要求在请求头中包含 Authorization 字段。
// routes/protected.js
const express = require('express');
const router = express.Router();
/**
* @swagger
* /protected:
* get:
* summary: 受保护的 API
* tags: [Protected]
* security:
* - bearerAuth: []
* responses:
* 200:
* description: 访问成功
* 401:
* description: 未授权
*/
router.get('/protected', (req, res) => {
const authHeader = req.headers.authorization;
if (authHeader) {
// 这里可以验证授权信息
res.send('访问成功');
} else {
res.status(401).send('未授权');
}
});
// 定义安全方案
const swaggerSecurity = {
securityDefinitions: {
bearerAuth: {
type: 'apiKey',
name: 'Authorization',
in: 'header',
},
},
};
module.exports = { router, swaggerSecurity };
在 Swagger UI 中，我们可以点击右上角的 Authorize 按钮，在弹出的对话框中输入 Bearer 加上令牌，例如 Bearer 123456。
3.1.2 设置 Content-Type 请求头
如果我们的 API 接口接收 JSON 格式的请求体，那么需要设置 Content-Type 请求头为 application/json。
// routes/json.js
const express = require('express');
const router = express.Router();
/**
* @swagger
* /json:
* post:
* summary: 接收 JSON 请求
* tags: [JSON]
* consumes:
* - application/json
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* message:
* type: string
* responses:
* 200:
* description: 成功接收 JSON 请求
*/
router.post('/json', (req, res) => {
const jsonData = req.body;
res.send(`接收到 JSON 数据：${jsonData.message}`);
});
module.exports = router;
在 Swagger UI 中，当我们选择请求体格式为 application/json 时，Swagger 会自动设置 Content-Type 请求头。
3.2 自定义请求头
除了常见的请求头，我们还可以自定义请求头。例如，我们需要在请求头中添加一个 X-Custom-Header 字段。
// routes/custom-header.js
const express = require('express');
const router = express.Router();
/**
* @swagger
* /custom-header:
* get:
* summary: 自定义请求头测试
* tags: [Custom Header]
* parameters:
* - in: header
* name: X-Custom-Header
* schema:
* type: string
* description: 自定义请求头
* responses:
* 200:
* description: 成功获取自定义请求头
*/
router.get('/custom-header', (req, res) => {
const customHeader = req.headers['x-custom-header'];
res.send(`自定义请求头的值为：${customHeader}`);
});
module.exports = router;
在 Swagger UI 中，我们可以在请求头输入框中输入 X-Custom-Header 及其值。
四、技术优缺点
4.1 优点
- 提高开发效率：无需编写额外的测试代码，直接在界面上进行 API 测试，节省了开发时间。
- 方便团队协作：清晰的 API 文档和可视化界面，方便团队成员之间的沟通和协作。
- 易于维护：Swagger 可以自动生成 API 文档，当 API 发生变化时，只需要更新 Swagger 配置即可。
4.2 缺点
- 依赖配置：需要正确配置 Swagger 才能正常使用，如果配置不当，可能会导致 API 文档和测试出现问题。
- 功能有限：对于一些复杂的测试场景，Swagger UI 可能无法满足需求，需要使用其他测试工具。
五、注意事项
5.1 配置准确性
在使用 Swagger UI 时，要确保 Swagger 配置的准确性，包括 API 路由、参数、响应等信息。如果配置错误，可能会导致 API 测试失败。
5.2 安全问题
在设置请求头时，要注意安全问题，特别是 Authorization 请求头，要确保令牌的安全性，避免泄露。
5.3 兼容性
不同版本的 Swagger UI 可能存在兼容性问题，在使用时要注意版本的选择。
六、文章总结
本文介绍了如何使用 Swagger UI 进行 API 测试，重点讲解了如何处理复杂参数和请求头设置。通过具体的示例，展示了如何处理数组、对象、嵌套参数，以及如何设置常见和自定义请求头。同时，分析了 Swagger UI 的优缺点和使用时的注意事项。希望本文能帮助开发者更好地使用 Swagger UI 进行 API 测试。
Comments