Spring Boot 3 openapi3 swagger3 整合

编程教程 > Java > Spring (500) 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",...
1.iperf3简介iPerf3是用于主动测试IP网络上最大可用带宽的工具。它支持时序、缓冲区、协议(TCP,UDP,SCTP与IPv4和IPv6)有关的各种参
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文档生成
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...
Java编程之Spring Boot 使用SLF4J Logging,spring boot,SLF4J
前言本文主要对新路由3 D2和小米路由3G做一个实际的使用测评
一、Newifi 3(新路由3) D2刷Breed资源准备​硬件准备:Newifi 3(新路由3) D2 原厂固件路由器一台;电脑一台;网线一根; 软件准备:winscp( 文件复制工具)put...