1. 准备Debian系统环境
确保Debian系统已更新至最新状态，并安装必要的基础工具（如curl、git）及Node.js运行环境（Swagger UI及相关工具依赖Node.js）：
sudo apt update && sudo apt upgrade -y
sudo apt install curl git nodejs npm -y
验证Node.js和npm安装版本：
nodejs -v && npm -v
（注：建议使用Node.js LTS版本，避免兼容性问题。）
2. 安装Swagger UI工具
Swagger UI是可视化测试API的核心工具，可通过以下两种方式安装：
使用npm（Node.js包管理器）全局安装swagger-ui-express（用于在Express应用中集成Swagger UI）和swagger-jsdoc（用于从代码注释生成Swagger文档）：
sudo npm install -g swagger-ui-express swagger-jsdoc
安装完成后，可通过swagger-ui-express --version验证是否安装成功。
若不想污染系统环境，可使用Docker运行Swagger UI容器：
sudo apt install docker.io -y
sudo systemctl start docker && sudo systemctl enable docker
docker pull swaggerapi/swagger-ui:v4.15.5 # 拉取最新版Swagger UI镜像
docker run -d -p 8080:8080 --name swagger-ui -v $(pwd)/swagger.json:/app/swagger.json swaggerapi/swagger-ui:v4.15.5 # 挂载本地swagger.json文件
容器启动后，通过http://localhost:8080访问Swagger UI界面。
3. 创建Swagger规范文件
Swagger规范文件（swagger.json或swagger.yaml）是API的“说明书”，需描述接口的路径、方法、参数、响应等信息。以下是一个简单的swagger.json示例：
{
"swagger": "2.0",
"info": {
"title": "Debian API测试示例",
"description": "用于演示Swagger在Debian上的API测试流程",
"version": "1.0.0"
},
"basePath": "/api",
"schemes": ["http"],
"paths": {
"/users": {
"get": {
"summary": "获取用户列表",
"description": "返回系统中的所有用户信息",
"responses": {
"200": {
"description": "成功返回用户列表",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {"type": "integer"},
"name": {"type": "string"},
"email": {"type": "string"}
}
}
}
}
}
}
}
}
}
将上述内容保存为swagger.json（或转换为YAML格式），并存放在项目根目录。
4. 集成Swagger UI到应用（可选但推荐）
若需在应用中直接查看和测试API，可将Swagger UI集成到Express框架中：
mkdir debian-swagger-api && cd debian-swagger-api
npm init -y
npm install express swagger-ui-express swagger-jsdoc -S
新建app.js文件，内容如下：
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
// Swagger配置选项
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'Debian API测试',
version: '1.0.0',
description: '通过Swagger UI测试Debian上的API'
},
servers: [{ url: 'http://localhost:3000' }]
},
apis: ['./swagger.json'] // 指向Swagger规范文件
};
const specs = swaggerJsdoc(options);
const app = express();
const PORT = 3000;
// 集成Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
// 示例API接口（需与swagger.json中的路径一致）
app.get('/api/users', (req, res) => {
res.json([
{ id: 1, name: '张三', email: 'zhangsan@example.com' },
{ id: 2, name: '李四', email: 'lisi@example.com' }
]);
});
app.listen(PORT, () => {
console.log(`应用运行在 http://localhost:${PORT}`);
console.log(`Swagger UI界面: http://localhost:${PORT}/api-docs`);
});
node app.js
打开浏览器，访问http://localhost:3000/api-docs，即可看到Swagger UI界面，其中包含/api/users接口的详细信息。
5. 使用Swagger UI测试API
在Swagger UI界面中，找到目标接口（如/api/users的GET方法），点击右侧的Try it out按钮：
6. 使用curl命令行工具测试（可选）
若习惯使用命令行，可通过curl直接调用API接口，验证其功能：
# 测试GET接口（无参数）
curl -X GET http://localhost:3000/api/users
# 测试GET接口（带查询参数，如分页）
curl -X GET "http://localhost:3000/api/users?page=1&limit=10"
# 测试POST接口（需提供JSON body，如创建用户）
curl -X POST http://localhost:3000/api/users \
-H "Content-Type: application/json" \
-d '{"name": "王五", "email": "wangwu@example.com"}'
根据接口定义调整请求方法、路径和参数，查看响应结果是否符合预期。
注意事项
-H添加认证头；