如何在Linux上使用Swagger进行API接口调试

一、准备工作：安装基础工具

在Linux上使用Swagger进行API调试前，需先安装Node.js（提供npm包管理器）和Docker（可选，用于快速部署Swagger Editor/UI）。

安装Node.js和npm（适用于Debian/Ubuntu系统）：
```
sudo apt update && sudo apt install -y nodejs npm 
```
安装Docker（可选，用于容器化部署）：
参考Docker官方文档安装Docker Engine，确保docker命令可用。

二、安装Swagger工具

1. 方式一：通过npm安装（适合开发环境）

安装Swagger Editor（在线编辑API规范）：
```
sudo npm install -g swagger-editor 
```
安装Swagger UI（可视化调试界面）：
```
sudo npm install -g swagger-ui 
```
启动服务：
- Swagger Editor：运行swagger-editor，默认访问http://localhost:9000；
- Swagger UI：运行swagger-ui，默认访问http://localhost:8080。

2. 方式二：通过Docker安装（推荐，避免环境冲突）

拉取Swagger Editor镜像：

docker pull swaggerapi/swagger-editor:v4.6.0

运行Editor容器（映射端口8080）：

docker run -d -p 38080:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0

拉取Swagger UI镜像：

docker pull swaggerapi/swagger-ui:v4.15.5

运行UI容器（映射端口38081）：

docker run -d -p 38081:8080 --name swagger-ui swaggerapi/swagger-ui:v4.15.5

访问地址：
- Swagger Editor：http://<Linux服务器IP>:38080；
- Swagger UI：http://<Linux服务器IP>:38081。

三、配置API文档

1. 编写Swagger规范文件

创建swagger.yaml（或swagger.json）文件，定义API的基本信息、路径、参数、响应等。示例如下：

swagger: '2.0' info: title: Linux API调试示例 version: 1.0.0 description: 用于演示Linux环境下Swagger调试的API basePath: /api/v1 schemes: - http paths: /user/{id}: get: summary: 根据用户ID获取用户信息 description: 返回指定ID的用户详情 parameters: - name: id in: path required: true type: integer description: 用户唯一标识 responses: '200': description: 成功获取用户信息 schema: type: object properties: id: type: integer name: type: string '404': description: 用户不存在

2. 集成到应用（可选，适合后端项目）

若使用Spring Boot框架，可通过依赖和配置自动生成Swagger文档：

添加Maven依赖（pom.xml）：

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>

配置Swagger（Java配置类）：

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 替换为你的Controller包路径 .paths(PathSelectors.any()) .build(); } }

启动应用：访问http://<服务器IP>:8080/swagger-ui.html（Spring Boot默认端口）即可查看文档。

四、启动Swagger服务并调试

1. 使用Swagger Editor编辑规范

访问http://localhost:9000（本地）或http://<服务器IP>:38080（远程），在线编写/修改swagger.yaml文件；
实时校验YAML语法，确保API定义符合OpenAPI规范。

2. 使用Swagger UI调试接口

访问http://localhost:8080（本地）或http://<服务器IP>:38081（远程），加载swagger.yaml文件；
在界面上找到目标接口（如/user/{id}/get），填写路径参数（如id: 1）；
点击Try it out按钮，发送请求；
查看Response区域，获取接口返回结果（如状态码、响应体）。

3. 使用curl命令辅助测试（可选）

若不想用Swagger UI，可通过curl命令直接测试接口：

GET请求（带路径参数）：

curl -X GET "http://<服务器IP>:8080/api/v1/user/1"

POST请求（带JSON body）：

curl -X POST "http://<服务器IP>:8080/api/v1/user/create" \ -H "Content-Type: application/json" \ -d '{"name": "John Doe", "age": 30}'

POST请求（带表单参数）：

curl -X POST "http://<服务器IP>:8080/api/v1/user/login" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=admin&password=123456"

上传文件：

curl -X POST "http://<服务器IP>:8080/api/v1/upload" \ -F "file=@/path/to/local/file.txt" \ -F "description=Test file"

注意事项

端口冲突：若端口已被占用，可通过-p参数修改映射端口（如docker run -d -p 4000:8080）；
跨域问题：若API与Swagger UI不在同一域名下，需在后端配置CORS（如Spring Boot添加@CrossOrigin注解）；
文档更新：修改swagger.yaml后，需重启Swagger UI服务（若通过swagger serve启动）或刷新浏览器页面。