Spring Boot 3 openapi3 swagger3 整合

编程教程 > Java > Spring (553) 2024-11-26 14:39:04

前言

距离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("[email protected]")
.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,谨防冲突。

 

 

 


评论
User Image
提示:请评论与当前内容相关的回复,广告、推广或无关内容将被删除。

相关文章
前言距离springfox的swagger2.x 以及3.0.0 长久等待,等来了springdoc的swagger 3 为啥是3是因为支持openapi3.0
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.iperf3简介iPerf3是用于主动测试IP网络上最大可用带宽的工具。它支持时序、缓冲区、协议(TCP,UDP,SCTP与IPv4和IPv6)有关的各种参
1.前言通过前面的两篇博客Spring Boot Security Swagger2整合生成安全的在线REST API文档 SpringMVC也可参考spring boot REST 通过Swa...
Swagger Spring Boot Stater简介spring boot 整合 springfox 实现swagger api文档生成
Intel Core I3 4130对比I3 4130T,标准版与节能版区别对比,Intel Core I3 4130对比I3 4130T区别优缺,i3 4130T
【重要提示】:目前已有更好的方法,可以参考:Swagger2 导出离线 word文档一、使用背景    如今,REST和微服务已经有了很大的发展势头
概述Vue3 + Vite 打包整合到Spring boot项目,两种模式。单一项目和多重项目单一项目:vue 单一项目整合到一个Spring Boot 项目多
Newifi3 D2 硬件参数信息 Newifi3 D2 硬件配置信息 SOCMT7621A2.4G无线芯片MT7603EN5G 无线芯片MT7612EN5G 功放芯片SKY85717-21RA...
Tess4J 与Tesseract版本关系0.4 (Tesseract 2.04)1.0 (Tesseract 3.02)1.1 (Tesseract 3.02
Java编程之Spring Boot 使用SLF4J Logging,spring boot,SLF4J
前言本文主要对新路由3 D2和小米路由3G做一个实际的使用测评