ubuntu swagger兼容性问题怎么解决 - 问答

Ubuntu环境下Swagger兼容性问题的常见解决方法

1. 解决JDK版本兼容问题

Swagger（尤其是SpringFox集成方案）对JDK版本有明确要求，旧版JDK（如Java 8）可能导致启动错误。需升级至推荐的JDK 11及以上版本。
操作步骤：

检查当前JDK版本：java -version；
卸载旧版JDK（如OpenJDK 8）：sudo apt remove openjdk-8-jdk；
安装JDK 11：sudo apt install openjdk-11-jdk；
验证安装：java -version（需显示版本为11及以上）。

2. 处理Spring Boot与Swagger版本兼容

Spring Boot版本升级后，需同步调整Swagger依赖版本以避免冲突。例如，Spring Boot 3.x需配合SpringDoc（而非旧版SpringFox）使用。
操作步骤：

移除SpringFox依赖（若已添加）：在pom.xml中删除springfox-boot-starter相关条目；
添加SpringDoc依赖：在pom.xml中加入org.springdoc:springdoc-openapi-ui（版本需适配Spring Boot，如2.0.2+）；
修改配置类：将@EnableSwagger2替换为@EnableOpenApi，并调整Docket的DocumentationType为OPEN_API_3_0。

3. 修复依赖冲突

高版本Spring Boot与Swagger可能因路径匹配策略（如Jakarta EE 9+的jakarta.servlet包）引发冲突，导致启动失败。
解决方法：

排除Spring Boot自带的jakarta.servlet-api依赖，在pom.xml中添加：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>jakarta.servlet</groupId>
            <artifactId>jakarta.servlet-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

添加兼容的javax.servlet-api依赖（版本4.0.1+）：

<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
    <scope>provided</scope>
</dependency>

4. 正确部署Swagger UI

Ubuntu环境下，Swagger UI可通过多种方式运行，选择合适的方式可避免环境兼容问题：

Docker方式（推荐）：
- 安装Docker：sudo apt install docker.io；
- 拉取Swagger UI镜像：docker pull swaggerapi/swagger-ui；
- 运行容器：docker run -p 8080:8080 swaggerapi/swagger-ui；
- 访问：http://localhost:8080。
npm方式：
- 安装Node.js和npm：sudo apt install nodejs npm；
- 全局安装Swagger UI：sudo npm install -g swagger-ui；
- 启动服务：swagger-ui（默认端口8080）。
手动下载方式：
- 从GitHub下载指定版本的Swagger UI（如v3.48.0）：wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz；
- 解压并进入目录，安装依赖：npm install；
- 启动服务器：npm start（默认端口3000）。

5. 配置跨域与鉴权

若API服务器启用了CORS（跨域资源共享）或鉴权（如JWT Token），需在Swagger UI中配置对应参数：

跨域配置：在API服务器（如Spring Boot）中添加CORS支持，或在Swagger UI的index.html中配置requestInterceptor注入Token：

requestInterceptor: (request) => {
    request.headers['Authorization'] = 'Bearer ' + localStorage.getItem('token');
    return request;
}

6. 升级至Swagger 3（OpenAPI 3）

Swagger 2已于2017年停止维护，建议升级至Swagger 3（OpenAPI 3）以获得更好的兼容性和功能支持：

移除SpringFox依赖，添加SpringDoc依赖（参考步骤2）；
将注解从io.swagger.annotations替换为io.swagger.v3.oas.annotations（如@ApiOperation→@Operation）；
修改Swagger配置类（参考步骤2），并调整swagger.json/swagger.yaml的openapi版本为3.0.0。

0 赞

0 踩