如何在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接口

通过Swagger Editor：
- 在Editor中编写swagger.yaml或swagger.json文件（描述API路径、参数、响应等）。
- 点击右上角**“Validate”**验证文档语法，无误后保存。
通过Swagger UI：
- 打开Swagger UI界面，找到目标API端点（如/api/hello）。
- 点击**“Try it out”**按钮，输入必要参数（如Query、Body）。
- 点击**“Execute”**发送请求，查看响应结果（状态码、Headers、Body）。
结合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的调试，覆盖文档生成、接口测试、安全验证等场景。