SpringBoot 3.x + Swagger3 踩坑实录

news2025/1/16 15:58:37

问题描述

维护的SpringBoot版本是3.0版本，翻教程的时候发现很多SpringBoot2.x版本用的都是springfox，但问题是在SpringBoot3.x版本后，逐渐不支持springfox，强行启动会导致异常，现阶段使用的Springdoc进行替换。

参考网站

一切以官方文档为准。

（该份文档介绍了如何从Springfox进行迁移）

用于 spring-boot 的 OpenAPI 3 库 (springdoc.org)https://springdoc.org/#Introduction

快速开始 | Knife4j (xiaominfo.com)https://doc.xiaominfo.com/docs/quick-start

依赖

 <!--添加swagger核心依赖-->
        <!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-core -->
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-core</artifactId>
            <version>2.2.20</version>
        </dependency>
 <!--添加knife4j依赖-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.4.0</version>
        </dependency>
 <!--添加Springdoc依赖-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
            <version>2.2.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>

 <!--仅添加上述依赖，仍有可能报错，需补充以下依赖-->
        <dependency>
            <groupId>com.fasterxml.jackson.module</groupId>
            <artifactId>jackson-module-jakarta-xmlbind-annotations</artifactId>
            <version>2.13.3</version>
        </dependency>

        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.4.0-b180830.0359</version>
        </dependency>

关于依赖介绍如上，最初因为没有添加最后两个依赖，程序报错如下：

Spring Boot 3 throws NoClassDefFoundError - javax/xml/bind/annotation/XmlElement

搜索后发现是jdk的问题，javax.xml.bind.annotation在jdk11中已被移除，所以为了解决该问题，需要加入上面最后两个依赖。

yml配置

server:
  port: 8080
  servlet:
    context-path: /api

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.moudel.xxx.controller

配置config

package com.moudel.xxx.config;

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

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI swaggerOpenAPI(){
        return new OpenAPI()
                .info(new Info().title("标题")
                        .contact(new Contact())
                        .description("我的API文档")
                        .version("v1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("https://springshop.wiki.github.org/docs"));
    }
}

创建Controller案例

package com.moudel.xxx.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "首页模块")
@RestController
public class IndexController {

    @Parameter(name = "name",description = "姓名",required = true)
    @Operation(summary = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}