Ubuntu上Swagger测试API的方法

Ubuntu上使用Swagger测试API的完整流程

1. 前置准备：安装Node.js和npm

Swagger Editor和Swagger UI的安装依赖Node.js环境，需先通过以下命令安装：

sudo apt update
sudo apt install -y nodejs npm
# 验证安装
node -v  # 查看Node.js版本
npm -v   # 查看npm版本

2. 安装Swagger Editor（可选，用于API文档编辑与测试）

Swagger Editor提供可视化的API文档编写和实时测试功能，支持本地部署或Docker运行：

方式一：npm全局安装+http-server启动

npm install -g swagger-editor
npm install -g http-server
# 进入Swagger Editor目录并启动
cd /usr/local/lib/node_modules/swagger-editor
http-server -p 8080

访问http://localhost:8080即可打开编辑器，默认加载Petstore示例API。

方式二：Docker运行

docker pull swaggerapi/swagger-editor
docker run -d -p 8888:8080 swaggerapi/swagger-editor

访问http://localhost:8888进入编辑器。

使用方法：
点击顶部菜单栏「File」→「Import」→「Open File」，选择本地的swagger.yaml或swagger.json文件；编辑完成后，可直接在界面上点击接口右侧的「Try it out」按钮，输入参数并执行测试，查看响应结果。

3. 安装Swagger UI（必用，用于API文档可视化与测试）

Swagger UI是官方推荐的API文档展示工具，支持在线测试接口，常见安装方式如下：

方式一：npm全局安装+Express集成

npm install -g swagger-ui-express express
mkdir swagger-ui-project && cd swagger-ui-project
npm init -y
# 创建server.js文件
echo "const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const app = express();
const swaggerDocument = YAML.load('./swagger.yaml'); // 加载本地API文档
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
const PORT = 3000;
app.listen(PORT, () => console.log(\`Server running on http://localhost:\${PORT}\`));" > server.js
# 启动服务
node server.js

访问http://localhost:3000/api-docs即可查看Swagger UI界面。

方式二：Docker运行

docker pull swaggerapi/swagger-ui
mkdir swagger-docs && cp /path/to/your/swagger.yaml swagger-docs/
docker run -d -p 8080:8080 -e SWAGGER_JSON=/app/swagger.yaml -v $(pwd)/swagger-docs:/app swaggerapi/swagger-ui

访问http://localhost:8080，页面会自动加载swagger.yaml文件。

方式三：直接下载源码运行
```
git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm install
npm start
```
访问http://localhost:3000/swagger-ui/index.html，修改dist/index.html中的url字段（指向你的API文档地址）即可自定义文档来源。

4. 配置API文档路径

无论是Swagger Editor还是Swagger UI，都需要指定API文档的位置：

Swagger Editor：默认加载https://petstore.swagger.io/v2/swagger.json，可通过编辑index.html文件修改defaultDocument变量，指向本地或远程文档。
Swagger UI：在启动配置中指定文档路径（如上述Docker命令中的-e SWAGGER_JSON或server.js中的YAML.load('./swagger.yaml')）。

5. 使用Swagger UI测试API

启动Swagger UI后，按照以下步骤进行接口测试：

导入文档：在页面右上角点击「Explore」按钮，输入API文档的URL（如http://localhost:8080/v2/api-docs）或选择本地swagger.yaml文件，点击「Import」。
选择接口：在左侧「Paths」面板中找到目标接口（如/users/get），点击展开。
输入参数：根据接口定义填写「Parameters」部分的参数（如查询参数、路径参数、请求体等），支持自动格式校验。
执行测试：点击接口下方的「Try it out」按钮，Swagger UI会自动发送HTTP请求到后端服务。
查看结果：在「Responses」面板中查看响应状态码（如200表示成功）、响应头和响应体（如JSON格式的数据）。

6. 常见问题解决

端口冲突：若默认端口（8080、3000）被占用，可在启动命令中修改端口（如-p 8081:8080）。
文档无法加载：检查API文档路径是否正确，确保后端服务已启动并暴露了Swagger文档接口（如Spring Boot项目的/v2/api-docs）。
权限问题：若使用Docker运行，确保当前用户对挂载目录有读写权限（如chmod -R 777 swagger-docs）。

通过以上步骤，即可在Ubuntu系统上使用Swagger完成API文档的编辑、展示和在线测试，提升开发效率。