如何在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启动）或刷新浏览器页面。

0 赞

0 踩