如何在CentOS上调试Swagger API

在CentOS上调试Swagger API的完整步骤

1. 准备基础环境

调试Swagger前需安装Java（JDK 8+）、Maven、Node.js/npm（用于构建和运行Swagger工具）：

# 安装Java（OpenJDK 11）
sudo yum install -y java-11-openjdk-devel
# 安装Maven
sudo yum install -y maven
# 安装Node.js和npm（CentOS 7/8通用）
curl -sL https://rpm.nodesource.com/setup_16.x | sudo bash -
sudo yum install -y nodejs
# 验证安装
java -version &
    &
     mvn -version &
    &
     node -v &
    &
     npm -v

2. 安装Swagger工具

方式一：Docker安装（推荐，无需本地构建）

# 拉取Swagger Editor镜像（可视化编辑API文档）
docker pull swaggerapi/swagger-editor:v4.6.0
# 运行Editor容器（映射端口8080）
docker run -d -p 8080:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0

# 拉取Swagger UI镜像（测试API接口）
docker pull swaggerapi/swagger-ui:v4.15.5
# 运行UI容器（映射端口8081，--network host共享宿主机网络）
docker run -d -p 8081:8080 --network host --name swagger-ui swaggerapi/swagger-ui:v4.15.5

访问http://< CentOS-IP> :8080进入Swagger Editor，http://< CentOS-IP> :8081进入Swagger UI。

方式二：本地安装（适合自定义配置）

# 安装Swagger Editor（全局）
sudo npm install -g swagger-editor
# 启动Editor（默认端口8080）
swagger-editor

# 安装Swagger UI（本地）
mkdir -p /opt/swagger-ui &
    &
 cd /opt/swagger-ui
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.52.5.tar.gz
tar -xzf v3.52.5.tar.gz --strip-components=1
npm install
# 构建静态文件
npm run build

将/opt/swagger-ui/dist目录内容复制到Web服务器根目录（如Apache的/var/www/html）。

3. 配置Swagger UI

若使用本地安装的Swagger UI，需修改dist/index.html文件，指定API文档地址（如api-docs接口）：

// 找到以下代码段并修改url为你的API文档路径
window.onload = function() {

  const ui = SwaggerUIBundle({
    
    url: "http://<
    CentOS-IP>
:8080/v3/api-docs", // 替换为你的Spring Boot应用地址
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  }
    );

}
    ;
    

4. 配置后端应用生成API文档

以Spring Boot为例，添加Swagger依赖并配置：

<
    !-- pom.xml 添加Swagger依赖 -->
    
<
    dependency>
    
  <
    groupId>
    org.springdoc<
    /groupId>
    
  <
    artifactId>
    springdoc-openapi-starter-webmvc-ui<
    /artifactId>
    
  <
    version>
    2.1.0<
    /version>
    
<
    /dependency>
    

创建配置类SwaggerConfig.java：

import io.swagger.v3.oas.models.OpenAPI;
    
import io.swagger.v3.oas.models.info.Info;
    
import org.springframework.context.annotation.Bean;
    
import org.springframework.context.annotation.Configuration;


@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
    
        return new OpenAPI()
                .info(new Info()
                        .title("CentOS Swagger API")
                        .version("1.0")
                        .description("API文档调试示例"))
                .servers(List.of(new Server().url("http://localhost:8080")));
 // 后端服务地址
    }

}
    

启动Spring Boot应用后，访问http://< CentOS-IP> :8080/swagger-ui.html即可查看自动生成的文档。

5. 调试API接口

1. 通过Swagger Editor：

   • 在Editor中编写swagger.yaml或swagger.json文件（描述API路径、参数、响应等）。
   • 点击右上角**“Validate”**验证文档语法，无误后保存。

2. 通过Swagger UI：

   • 打开Swagger UI界面，找到目标API端点（如/api/hello）。
   • 点击**“Try it out”**按钮，输入必要参数（如Query、Body）。
   • 点击**“Execute”**发送请求，查看响应结果（状态码、Headers、Body）。

3. 结合Burp Suite安全测试：

   • 配置Burp Suite作为代理（监听8080端口）。
   • 在Swagger UI的Settings→General中设置代理为http://< Burp-IP> :8080。
   • 捕获Swagger UI发送的请求，修改参数进行安全测试（如SQL注入、XSS）。

6. 常见问题解决

• 无法访问Swagger UI：检查防火墙是否开放端口（sudo firewall-cmd --add-port=8081/tcp --permanent & & sudo firewall-cmd --reload）。
• API文档无法加载：确保后端应用的/v3/api-docs接口可访问（无认证拦截或CORS问题）。
• Docker容器无法联网：使用--network host参数运行容器（仅限Linux），或配置Docker网络。

通过以上步骤，可在CentOS上完成Swagger API的调试，覆盖文档生成、接口测试、安全验证等场景。

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