前言
距离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增加了配置
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
如果考虑使用knife4j 增强功能则需要引入knife4j的starter并移除springdoc的starter，谨防冲突。
https://www.leftso.com/article/2408231727599086.html
相关文章
前言距离springfox的swagger2.x 以及3.0.0 长久等待，等来了springdoc的swagger 3 为啥是3是因为支持openapi3.0
Swagger Spring Boot Stater简介spring boot 整合 springfox 实现swagger api文档生成
【重要提示】：目前已有更好的方法，可以参考：Swagger2 导出离线 word文档一、使用背景 如今，REST和微服务已经有了很大的发展势头
springfox swagger 请求参数类型设置解析类：springfox.documentation.spring.web.readers.parameter.ParameterTypeR...
升级环境说明目前项目使用的2.3.7版本（自己感觉还行，但是官方已经停止支持了。）Spring Boot 官方支持情况spring boot 官方支持情况官方在今年8月就终止了对2.3.x的版本...
前言使用Spring Boot 3 Security 6.2 JWT 完成无状态的REST接口认证和授权管理。环境JDK 17Spring Boot 3.3.2
创建REST API时，良好的文档是有帮助的。而且，API中的每一个变化都应该在参考文档中同时描述。手动完成这是一个乏味的操作，因此这个过程的自动化是不可避免的。
Java编程之Spring Boot 使用SLF4J Logging,spring boot,SLF4J
从Spring 6和Spring Boot 3开始，与OpenFeign和Retrofit等其他声明式客户端类似，Spring框架支持以Java接口的形式创建RSocket服务，并为RSocke...
从Spring 6和Spring Boot 3开始，Spring framework支持将远程HTTP服务代理为带有HTTP交换注解方法的Java接口。类似的库，如OpenFeign和Retro...
从Spring 6和Spring Boot 3开始，Spring框架支持“HTTP API的问题详细信息”规范RFC 7807。本Spring Boot 教程将详细指导您完成这一新增强。1.问题...
环境JDK 17Spring Boot 3.2.1-3.2.3Spring Security 6.2.1-6.3.1Spring Security 权限/角色常
一、SpringBoot默认的错误处理机制1）浏览器，返回一个默认的错误页面2）如果是其他客户端（app），默认响应一个json数据（postman模拟）客户端