Spring Boot 使用 SpringDoc 库的 Swagger3.0
Swagger 定义
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
SpringFox 的 Swagger 库
之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库,上了下官网发现已经有接近两年没出新版本了!前几天升级了SpringBoot 2.6.x 版本,发现这个库的兼容性也越来越不好了,有的常用注解属性被废弃了居然都没提供替代!
https://search.maven.org/ 网站上可以查到它的最近一次版本发布时时间:14-Jul-2020。
引入依赖的方式如下
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Spring5使用PATH_PATTERN_PARSER来替代原本的ANT_PATH_MATCHER。SpringBoot2.6.0开始,Spring默认路径匹配策略从ANT_PATH_MATCHER改成PATH_PATTERN_PARSER。但Swagger没有对其做兼容,因此会报空指针异常。需要修改application.yml,添加如下配置
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
SpringDoc
后来在网上一查发现,现在大家都在用另一款Swagger库SpringDoc。官网地址为:https://springdoc.org/
SpringDoc是一款可以结合SpringBoot使用的API文档生成工具,基于OpenAPI 3,目前在Github上已有1.7K+Star,更新发版还是挺勤快的,是一款更好用的Swagger库!值得一提的是SpringDoc不仅支持Spring WebMvc项目,还可以支持Spring WebFlux项目,甚至Spring Rest和Spring Native项目,总之非常强大
依赖
https://search.maven.org/ 网站上可以查到它的最近一次版本发布时时间:16-Dec-2022。
引入依赖的方式如下
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>
包名
- 2.9.x
- io.swagger
- 3.0.0
- io.swagger.core.v3
- io.swagger.v3.oas.annotations
注解
这一步是可选的,因为改动太大,故 springfox对旧版的 swagger做了兼容处理。
Swagger2 的注解命名以易用性切入,全是 Api 开头,在培养出使用者依赖注解的习惯后,Swagger 3将注解名称规范化,工程化。
swagger2 | OpenAPI 3 | 注解位置 |
---|---|---|
@Api | @Tag(name=“接口描述”, description = “详细说明”) | Controller类上 |
@ApiOperation | @Operation(summary = “接口方法描述”, description = “详细说明”) | Controller方法上 |
@ApiImplicitParams | @Parameters | Controller 方法上 |
@ApiImplicitParam | @Parameter(description=“参数描述”) | Controller 方法上 @Parameters 里 |
@ApiParam | @Parameter(description=“参数描述”) | Controller 方法的参数上 |
@ApiIgnore | @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden | - |
@ApiModel | @Schema | DTO类上(Data Transfer Object) |
@ApiModelProperty | @Schema | DTO属性上(Data Transfer Object) |
常用配置
SpringDoc还有一些常用的配置
springdoc:
swagger-ui:
# 修改Swagger UI路径
path: /swagger-ui.html
# 开启Swagger UI界面
enabled: true
api-docs:
# 修改api-docs路径
path: /v3/api-docs
# 开启api-docs
enabled: true
# 配置需要生成接口文档的扫描包
packages-to-scan: com.macro.mall.tiny.controller
# 配置需要生成接口文档的接口路径
paths-to-match: /brand/**,/admin/**
访问地址
- 2.9.x
http://localhost:8081/{context-path}/swagger-ui.html - 3.0.0
http://localhost:8081/{context-path}/swagger-ui/index.html
英文单词解释
- explicit关键字
只能修饰只有一个参数的构造函数,或者有多个参数,但是除第一个参数外其他的参数都有默认值。它的作用是表明构造函数是显式方式显示的(当我们不希望自动类型转换的时候用。标准库好多构造函数都是explicit的) - implicit关键字
与explicit对应,他表示隐式的进行数据转换(在需要隐式转换的时候用)。注:C++中不存在这个关键字,C#等编程语言中才有 - DTO
Data Transfer Object,即数据传输对象。用于表现层和应用层之间的数据交互 简单来说Model面向业务,我们是通过业务来定义Model的。而DTO是面向界面UI,是通过UI的需求来定义的。 通过DTO我们实现了表现层与Model之间的解耦,表现层不引用Model(个人理解,就是Java Bean) - Controller
Spring Controller本身也是一个Spring Bean,只是它多提供了Web能力,只需要造类上提供 @Controller 或者 @RestController 注解即可
相关文章
- spring boot: 在maven中装入springframework框架
- Spring Boot 微服务性能下降九成!使用 Arthas 定位根因
- [Kotlin Spring boot] Connect template with a backing bean
- spring boot单元测试之十四:controller使用html模板时做单元测试(spring boot 2.4.4)
- spring boot:使用分布式事务seata(druid 1.1.23 / seata 1.3.0 / mybatis / spring boot 2.3.2)
- Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2
- Spring Boot (四): Druid 连接池密码加密与监控
- spring boot 配置文件占位符和多环境配置 [七]
- spring boot:分别在jar内部和外部使用配置文件(spring boot v2.5.4)
- intellij idea 2021.2:为一个spring boot项目改名
- spring boot:使用poi导出excel电子表格文件(spring boot 2.3.1)
- spring boot:使用mybatis访问多个mysql数据源/查看Hikari连接池的统计信息(spring boot 2.3.1)
- 使用 Docker 部署 Spring Boot 项目
- 使用外置tomcat部署spring boot程序需添加servlet-api
- Spring Boot整合Mybatis-Plus 增删改查+ 分页基本使用完整示例
- Spring Boot字符串转日期转换器示例
- Spring Boot:Data Rest Service
- MongoDB最简单的入门教程之四:使用Spring Boot操作MongoDB
- Spring Boot:定制PropertyEditors
- 【多数据源动态切换】Spring Boot中实现多数据源动态切换效果(2):通过开源项目Dynamic Datasource Spring Boot Starter实现
- 【日志系统最全】Spring Cloud Sleuth使用ELK收集&;分析日志
- Spring Boot使用外部配置文件
- Spring Boot框架中使用Jackson的处理总结
- 学习Spring Boot:(十九)Shiro 中使用缓存
- 学习Spring Boot:(十五)使用Lombok来优雅的编码
- 学习Spring Boot:(六) 集成Swagger2
- spring boot + thymeleaf +security自定义规则 的简单使用
- Spring Boot 使用 Groovy 模板引擎开发视图层
- 全网最详细的Spring Boot 整合数据源Druid DataSource以及监控mysql数据库的性能
- spring boot下使用logback或log4j生成符合Logstash标准的JSON格式
- 001-Spring Cloud Edgware.SR3 升级最新 Finchley.SR1,spring boot 1.5.9.RELEASE 升级2.0.4.RELEASE注意问题点
- 005-spring-data-elasticsearch 3.0.0.0使用【三】-spring-data之Spring数据扩展
- 009-Spring Boot 事件监听、监听器配置与方式、spring、Spring boot内置事件
- 007-Spring Boot-@Enable*注解的工作原理-EnableConfigurationProperties、ImportSelector、ImportBeanDefinitionRegistrar
- Java SpringBoot 应用使用命令行 mvn spring-boot run 启动的原理