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

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！