Spring Boot 3 openapi3 swagger3 整合

教程分享 > Java教程 > Spring > 博文分享 (1044) 2024-08-23 17:34:26

前言

距离springfox的swagger2.x 以及3.0.0 长久等待,等来了springdoc的swagger 3 为啥是3是因为支持openapi3.0规范(最新支持3.1)

环境

  • jdk17
  • spring boot 3.3.3

引入依赖

maven pom.xml 添加

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

编写配置

application.yml配置

#文档部分配置
springdoc:
api-docs:
enabled: true
version: openapi_3_1
groups:
enabled: true
swagger-ui:
display-request-duration: true
groups-order: desc
operations-sorter: method
disable-swagger-default-url: true
use-root-path: true
default-model-expand-depth: 5
# default-models-expand-depth: 5
show-actuator: true
group-configs:
- group: 用户中心模块
paths-to-match:
- /user/**
- group: 消息中心模块
paths-to-match:
- /msg/**
cache:
disabled: true

 

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
info = @Info(
title = "Spring Boot 3 + Swagger 3 API文档",
description = "使用spring boot 3 和Swagger 3 构建生成的API文档",
version = "v1.0.0"
)
)
public class Swagger3Config {



}

 

编写数据对象和接口

数据对象

@Schema(description = "用户信息")
@Data
@Builder
public class UserDTO {

@Schema(description = "用户id",title = "用户id")
private Long id;
@Schema(description = "账户")
private String username;
@Schema(description = "密码")
private String password;
@Schema(description = "邮箱")
private String email;
@Schema(description = "电话")
private String phone;
@Schema(description = "启用状态")
private Boolean enabled;
@Schema(description = "注册时间")
private Date createTime;
}

 

接口

@Tag(name = "用户业务处理con",description = "更多详细描述.......")
@RestController
public class UserController {


@Operation(summary = "用户信息列表(接口简介)",description = "接口详细描述哟",tags = "用户业务处理con",
parameters = {
@Parameter(name = "Authorization",description = "Bearer token令牌",in = ParameterIn.HEADER),
@Parameter(name = "pageNum",description = "当前页码",required = true,example = "1"),
@Parameter(name = "pageSize",description = "分页大小",required = true,example = "1"),

},
responses = {
@ApiResponse(responseCode = "200", description = "成功返回")
}
)
@GetMapping("/user/getUsers")
public List<UserDTO> getUsers(int pageNum, int pageSize) {
List<UserDTO> users = new ArrayList<>();
users.add(UserDTO
.builder()
.id(1L)
.username("admin")
.password("000000")
.email("123@qqq.com")
.phone("1859999999")
.enabled(true)
.createTime(new Date())
.build()
);
return users;
}

@Operation(summary = "用户信息删除",description = "传入一个用户id,删除它",
parameters = {
@Parameter(name = "Authorization",description = "Bearer token令牌",in = ParameterIn.HEADER),
@Parameter(name = "userId",description = "用户id",required = true,in = ParameterIn.PATH),
}
)
@DeleteMapping("/user/{userId}")
public Boolean delete(@PathParam("userId") Long userId) {
return Objects.nonNull(userId);
}



}

 

启动项目,打开地址: http://localhost:8080 自动跳转 http://localhost:8080/swagger-ui/index.html 这是因为我们在application.yml增加了配置

Spring Boot 3 openapi3 swagger3 整合_图示-3c03a6ce2509457b884a7511ae568058.png
接口列表

 

Spring Boot 3 openapi3 swagger3 整合_图示-6ab05a7d58d7468fa0e154aedb6caf25.png
接口详情

knife4j ui引入

如果觉得原生ui不好看,可以替换国内的knife4j

maven添加ui的依赖

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-ui</artifactId>
<version>4.5.0</version>
</dependency>

重启项目并打开knife4j的ui地址 :http://localhost:8080/doc.html

Spring Boot 3 openapi3 swagger3 整合_图示-30cb013c2d8048509daf5b2577f50dc5.png
knife4j ui

如果考虑使用knife4j 增强功能则需要引入knife4j的starter并移除springdoc的starter,谨防冲突。

 

 

 


相关文章
前言距离springfox的swagger2.x 以及3.0.0 长久等待,等来了springdoc的swagger 3 为啥是3是因为支持openapi3.0
本文章主要简单讲解目前流行的springMVC4+Spring4+MyBatis3(即SSM)框架整合
springfox swagger 请求参数类型设置解析类:springfox.documentation.spring.web.readers.parameter.ParameterTypeR...
前言使用Spring Boot 3 Security 6.2 JWT 完成无状态的REST接口认证和授权管理。环境JDK 17Spring Boot 3.3.2
swagger dataType 有那些2.6.x"int", "date", "string", "double", "float", "boolean", "byte", "object",...
Swagger2 导出离线文档简述继上一篇搬运国外的swagger2导出离线文档之后,最近发现国内一款不错的swagger ui组件和导出离线的方法,比之前的更简单优雅
1.前言通过前面的两篇博客Spring Boot Security Swagger2整合生成安全的在线REST API文档 SpringMVC也可参考spring boot REST 通过Swa...
Swagger Spring Boot Stater简介spring boot 整合 springfox 实现swagger api文档生成
I3 4130 可以说在2013年风靡一时的CPU,在2019年来看这款CPU怎么样呢?接下来用I3 4130同最近几代I3 6100/I3 7100/I3 8100跑个分试试
Intel Core I3 4130对比I3 4130T,标准版与节能版区别对比,Intel Core I3 4130对比I3 4130T区别优缺,i3 4130T
【重要提示】:目前已有更好的方法,可以参考:Swagger2 导出离线 word文档一、使用背景    如今,REST和微服务已经有了很大的发展势头
I3 9100T参数详情,I3 9100T性能参考,I3 9100T价格参考。I3 9100T是上一代I3 8100T的升级产品,具体怎么样,一起来看看吧。
I3 9300T参数详情,I3 9300T性能参考,I3 9300T价格参考。I3 9300T是上一代I3 8300T的升级产品,具体怎么样,一起来看看吧。
Intel I3 9100参数详细信息,Intel I3 9100 性能怎么样,Intel I3 9100 参考价格
Java编程之Spring Boot 使用SLF4J Logging,spring boot,SLF4J