Springboot3.x 与 Springdoc & swagger -- 迁移

一、背景

springboot升级为3.x时，swagger的迁移会出现一些问题，目前springboot3.x将 包javax下的所有内容都迁移到了jakarta下，比如HttpServletRequest, 而swagger还是使用的包javax, 导致出现不兼容的问题，因此可以使用springdoc来替代以前的swagger包.

二、步骤

1. webmvc只需导入一个jar包

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
	<version>2.0.2</version>
</dependency>

2. yml配置

######## swagger configuration ###############
springdoc:
  packages-to-scan: ##需要扫描的包,可以配置多个
    - com.hmy.azure.controller
  paths-to-exclude:  ##配置不包含在swagger文档中的api
    - /api/test/**
    - /api/mockito/data
  swagger-ui:
    enabled: true  #开启/禁止swagger,prod可以设置为false
    path: /swagger-ui.html  #swagger页面
  api-docs:
    enabled: true #开启/禁止api-docs, prod可以设置为false
    path: /api-docs #api的json文档
  use-management-port: false
  ### 设置为true时, management也需要设置
#  use-management-port: true
#  show-actuator: true

#management:
#  server:
#    port: 9090
#  endpoints:
#    web:
#      exposure:
#        include: openapi,swagger-ui

3. SpringDocConfiguration 配置文件

package com.hmy.azure.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 SpringDocConfiguration {
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(apiInfo())
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc Wiki Documentation")
                        .url("https://springdoc.org/v2"));
    }

    private Info apiInfo() {
        return new Info()
                .title("Azure Demo API Doc")
                .description("springfox swagger 3.0 demo")
                .version("1.0.0")
                .contact(new Contact()
                        .name("<Your name>")
                        .url("<Your url>")
                        .email("<Your email>")
                )
                .license(new License()
                        .name("Apache 2.0")
                        .url("http://www.apache.org/licenses/LICENSE-2.0.txt")
                );
    }
}

4. UserController类

package com.hmy.azure.controller;

import com.hmy.azure.bean.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/user")
public class UserController {

    @Operation(summary = "List users",description = "List users by conditions")
    @Parameters({
            @Parameter(in = ParameterIn.HEADER,name = "idToken",description = "The Authorization token",required = true),
            @Parameter(in = ParameterIn.QUERY,name = "status",description = "The user's status"),
            @Parameter(in = ParameterIn.QUERY,name = "department",description = "The user's department")
    })
    @GetMapping("/list")
    public ResponseEntity<Object> listUser(@RequestParam(required = false) String status,
                                          @RequestParam(required = false) String department){
        return ResponseEntity.ok("SUCCESS");
    }

    @Operation(summary = "Get a user",description = "Get user by id")
    @Parameter(in = ParameterIn.PATH,name = "id",description = "The user's id",required = true)
    @GetMapping("/{id}")
    public ResponseEntity<Object> getUserById(@PathVariable String id){
        return ResponseEntity.ok("SUCCESS");
    }

    @Operation(summary = "Create a user",description = "Create a user")
    @PostMapping
    public ResponseEntity<Object> createUser(@RequestBody User user){
        return ResponseEntity.ok("SUCCESS");
    }
}

三、效果图

P1：

P2：

P3:

四、遇到过的问题

问题： 找不到SwaggerWelcomeCommon类, 报错如下

Description:
Parameter 3 of method indexPageTransformer in org.springdoc.webmvc.ui.SwaggerConfig required a bean of type 'org.springdoc.webmvc.ui.SwaggerWelcomeCommon' that could not be found.
Action:
Consider defining a bean of type 'org.springdoc.webmvc.ui.SwaggerWelcomeCommon' in your configuration.

原因: yml中use-management-port设置为了true
解决方法：yml中设置 use-management-port: false
问题参考链接: SwaggerWelcomeCommon could not be found

五、相关链接

1. 注解的替换及使用见官方文档