一、背景
springboot升级为3.x时,swagger的迁移会出现一些问题,目前springboot3.x将 包javax下的所有内容都迁移到了jakarta下,比如HttpServletRequest, 而swagger还是使用的包javax, 导致出现不兼容的问题,因此可以使用springdoc来替代以前的swagger包.
二、步骤
- webmvc只需导入一个jar包
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.2</version>
</dependency>
- 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
- 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")
);
}
}
- 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