如何在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://:38080；
  • Swagger UI：http://: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.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
  dependency>
  <dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
  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启动）或刷新浏览器页面。

以上就是关于“如何在Linux上使用Swagger进行API接口调试”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！

简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm