SpringBoot 3.x + Swagger3 踩坑实录

问题描述

维护的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: 8080servlet:context-path: /apispringdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-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 {@Beanpublic 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);}
}