1 什么是 springdoc ?
网上冲浪🏄🏻♂️时，无意间发现 java web 应用程序的在线接口文档，除了耳熟能详的 swagger 之外，还有个 springdoc。这也许就叫惊喜( ͡• ͜ʖ ͡• )
还记得要使用 swagger2 的话，springboot 项目里面需要引入 springfox 的依赖。swagger2 遵循的是 OpenAPI 2 规范。现在已经有了 OpenAPI 3 规范，springdoc 便是 OpenAPI 3 和 springboot 的结合，是 springfox 的完美替代品。
springdoc 的底层是 swagger3，前端页面看起来和 swagger2 的差不多，但无奈我是个喜新厌旧的人🙃，就是想学它~
2 springdoc 基本信息
官网是 https://springdoc.org/ ，它不仅是官网，还是操作手册，里面说的很详细。
需要注意的是，上面的官网是新版本 2.x 的，如果要看 1.x 版本的官网，则访问 https://springdoc.org/v1/
3 maven 依赖
3.1 version 1.7.0 及之前
1.7.0 版本及之前的版本，支持 SpringBoot 2.x 和 Java 8，此时需要引入下面2个依赖：
<!-- springdoc 基础依赖，必须有它 -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>
<!--
如果你的项目里面使用到了 spring security 的话，
需要加上springdoc 配合 spring security 的依赖
-->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-security</artifactId>
<version>1.6.14</version>
</dependency>
关于 springdoc 配合 spring security 的知识，目前的我对此一无所知🤣。后面再研究它吧，先把基础操作弄明白 已经搞定啦，详见文末链接。
可以从 https://mvnrepository.com/ 里面查询到最新版，然后把 <version>1.6.14</version> 换成最新的。
3.2 新的 version 2.x 及之后
目前（2023年10月）最新的版本 version 2.2.0，支持的是 SpringBoot 3.x 和 Java 17，此时只需需要引入一个依赖：
<!-- 2选1：使用 spring-boot-starter-web 的时候，只用下面的 webmvc-ui 的依赖 -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>
<!-- 2选1：使用 spring-boot-starter-webflux 的时候，则用下面的 webflux-ui 的依赖 -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
<version>2.2.0</version>
</dependency>
mvc 和 webflux 的依赖，2选1就可以。它们俩的版本号是一致的。新版本 2.x 的注解，和 1.x 的一样。
4 正文来袭
4.1 给 Controller 加注解
主要就是下面 4 个注解：
-
@Tag用来设置 Controller 的名称和描述，类似于给 Postman 的 Collections 命名； -
@ApiResponses和@ApiResponse用来配置响应； -
@Operation用来设置接口名称和描述； -
@Parameter用来设置请求参数的描述、是否必填和示例。
@RestController
// 响应的 MediaType 都是 application/json
@RequestMapping(path = "/process-definition", produces = "application/json")
// Tag 注解, 给整个接口起了个名字 "流程定义", 描述是 "流程定义 API"
@Tag(name = "流程定义", description = "流程定义 API")
// ApiResponses 给每个接口提供一个默认的响应, 状态码是 200, 描述是 "接口请求成功"
@ApiResponses(@ApiResponse(responseCode = "200", description = "接口请求成功"))
public class ProcessDefinitionController {
// Operation 注解设置了接口名称, 接口描述
@Operation(summary = "上传 BPMN xml 字符串 并部署", description = "此接口处理的是 xml 字符串")
@PostMapping("/upload-and-deploy/bpmn-xml-str")
public JsonResult<?> uploadAndDeployBpmnXmlStr(@RequestBody BpmnXmlReq req) {
return JsonResult.of(CommonCodeEnum.OK);
}
@Operation(summary = "查询单个 bpmn xml 数据")
@GetMapping("/bpmn-xml")
public JsonResult<BpmnXmlResp> findBpmnXml(
// Parameter 注解设置了请求参数的描述, 是否必填 以及示例
@Parameter(description = "流程部署ID", required = true, example = "1234") String deployId,
@Parameter(description = "流程资源名称", required = true, example = "xxx.bpmn") String resourceName) {
return JsonResult.of(CommonCodeEnum.OK, new BpmnXmlResp());
}
}
启动项目后，效果如下图：
4.2 给 Model 加注解
@Data
// Schema 注解设置这个类的描述
@Schema(description = "bpmn xml 请求参数")
public class BpmnXmlReq {
// Schema 注解设置每个属性的描述和示例
@Schema(description = "bpmn文件的内容, 字符串格式", example = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>")
private String xml;
@Schema(description = "流程部署名称", example = "请假流程")
private String deployName;
}
@Schema(description = "json结构的响应")
public class JsonResult<T> {
@Schema(description = "状态码", example = "200")
private Integer code;
@Schema(description = "状态码对应的信息", example = "请求成功")
private String message;
@Schema(description = "给前端返回的 json 格式的内容")
private T content;
// 省略部分内容
}
效果如下图：
点击 Example Value 后面的 Schema 可以看到如下图的内容：
滑到页面的最下方，可以看到：
4.3 需要上传附件怎么办?
4.3.1 错误写法
先看下错误写法😁：
@Operation(summary = "上传 BPMN 文件并部署", description = "此接口处理的是文件流")
@PostMapping(path = "/upload-and-deploy/bpmn-file")
public JsonResult<DeploymentResp> uploadAndDeployBpmnFile(
@Parameter(description = "要上传的 BPMN 文件", required = true) MultipartFile file,
@Parameter(description = "流程部署的名称", required = true) @RequestParam String deployName) {
return processDefinitionService.uploadAndDeployBpmnFile(file, deployName);
}
效果如下：
这表明，springdoc 并不能根据接口的请求参数类型是 MultipartFile ，来自动识别出我们要的是上传附件。所以解决办法就是指明此接口需要媒体类型的是附件。
4.3.2 正确写法
代码如下，我们指明此接口消费的是 multipart/form-data 这种媒体类型。
@Operation(summary = "上传 BPMN 文件并部署", description = "此接口处理的是文件流")
@PostMapping(path = "/upload-and-deploy/bpmn-file", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public JsonResult<DeploymentResp> uploadAndDeployBpmnFile(
@Parameter(description = "要上传的 BPMN 文件", required = true) MultipartFile file,
@Parameter(description = "流程部署的名称", required = true) @RequestParam String deployName) {
return processDefinitionService.uploadAndDeployBpmnFile(file, deployName);
}
效果如下：
4.4 如何给 API 排序? 如何给 HTTP 方法排序?
😁这个也简单~ 参考官方文档 https://springdoc.org 的 5.2 swagger-ui properties 可知，有以下2个配置项可供我们给 API 和 HTTP 方法排序：
-
springdoc.swagger-ui.tagsSorter给 API 排序， 如果其值为alpha就表示按字母顺序排序。默认情况下（也就是不配置此项），API 的顺序由 swagger 自己决定（也就是没什么顺序）； -
springdoc.swagger-ui.operationsSorter给 HTTP 方法排序，其值为alpha同样表示按字母顺序排序，值为method表示根据 HTTP 请求的类型（顺序如下：DELETE > GET > POST > PUT）排序。默认情况下，Controller 代码里面，你写的是什么顺序，swagger 就给你展示什么顺序。
4.4.1 API 排序示例
Java 的 Controller 代码如下：
@Tag(name = "01 登录", description = "登录相关API")
public class AuthController {}
@Tag(name = "05 历史", description = "历史 API")
public class HistoryController {}
@Tag(name = "02 流程定义", description = "流程定义 API")
public class ProcessDefinitionController {}
@Tag(name = "03 流程实例", description = "流程实例 API")
public class ProcessInstanceController {}
@Tag(name = "04 任务", description = "任务 API")
public class TaskController {}
application.yml 部分内容如下：
springdoc:
swagger-ui:
# API 排序
tags-sorter: alpha
最终效果如下图所示：
4.4.2 HTTP 方法排序示例
application.yml 部分内容如下：
springdoc:
swagger-ui:
# API 排序
tags-sorter: alpha
# HTTP 方法排序
operations-sorter: method
最终效果如下图所示：
5 大功告成
springdoc 的基本使用，到这里就全部欧克了，so easy ~
至于它和 spring security 的配合，后续再说~文章来源：https://www.toymoban.com/news/detail-782369.html
6 传送门
- 功夫不负有心人，😁springdoc 和 SpringSecurity 的结合，我也研究好了，文档链接如下 《02_学习springdoc与SpringSecurity配合_使用访问令牌来认证》
- springdoc 与微服务的结合，文档链接如下 《03_学习springdoc与微服务结合_简述》
- springdoc 与 oauth2 结合，文档链接如下 《04_学习springdoc与oauth结合_简述》
感谢阅读~文章来源地址https://www.toymoban.com/news/detail-782369.html
到了这里，关于01_学习springdoc的基本使用的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
