01_学习springdoc的基本使用

文章目录

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/ ，它不仅是官网，还是操作手册，里面说的很详细。

3 maven 依赖

<!-- 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>

换成最新的。

4 正文来袭

4.1 给 Controller 加注解

  主要就是下面 4 个注解：

1. @Tag 用来设置 Controller 的名称和描述，类似于给 Postman 的 Collections 命名；
2. @ApiResponses 和 @ApiResponse 用来配置响应；
3. @Operation 用来设置接口名称和描述；
4. @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 ="接口请求成功"))publicclassProcessDefinitionController{// Operation 注解设置了接口名称, 接口描述@Operation(summary ="上传 BPMN xml 字符串 并部署", description ="此接口处理的是 xml 字符串")@PostMapping("/upload-and-deploy/bpmn-xml-str")publicJsonResult<?>uploadAndDeployBpmnXmlStr(@RequestBodyBpmnXmlReq req){returnJsonResult.of(CommonCodeEnum.OK);}@Operation(summary ="查询单个 bpmn xml 数据")@GetMapping("/bpmn-xml")publicJsonResult<BpmnXmlResp>findBpmnXml(// Parameter 注解设置了请求参数的描述, 是否必填 以及示例@Parameter(description ="流程部署ID", required =true, example ="1234")String deployId,@Parameter(description ="流程资源名称", required =true, example ="xxx.bpmn")String resourceName){returnJsonResult.of(CommonCodeEnum.OK,newBpmnXmlResp());}}

  启动项目后，效果如下图：

图1 总览

图2 第一个接口

图3 第二个接口

4.2 给 Model 加注解

@Data// Schema 注解设置这个类的描述@Schema(description ="bpmn xml 请求参数")publicclassBpmnXmlReq{// Schema 注解设置每个属性的描述和示例@Schema(description ="bpmn文件的内容, 字符串格式", example ="<?xml version=\"1.0\" encoding=\"UTF-8\"?>")privateString xml;@Schema(description ="流程部署名称", example ="请假流程")privateString deployName;}@Schema(description ="json结构的响应")publicclassJsonResult<T>{@Schema(description ="状态码", example ="200")privateInteger code;@Schema(description ="状态码对应的信息", example ="请求成功")privateString message;@Schema(description ="给前端返回的 json 格式的内容")privateT content;// 省略部分内容}

  效果如下图：

  点击 Example Value 后面的 Schema 可以看到如下图的内容：

  滑到页面的最下方，可以看到：

4.3 需要上传附件怎么办?

4.3.1 错误写法

  先看下错误写法😁：

@Operation(summary ="上传 BPMN 文件并部署", description ="此接口处理的是文件流")@PostMapping(path ="/upload-and-deploy/bpmn-file")publicJsonResult<DeploymentResp>uploadAndDeployBpmnFile(@Parameter(description ="要上传的 BPMN 文件", required =true)MultipartFile file,@Parameter(description ="流程部署的名称", required =true)@RequestParamString 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)publicJsonResult<DeploymentResp>uploadAndDeployBpmnFile(@Parameter(description ="要上传的 BPMN 文件", required =true)MultipartFile file,@Parameter(description ="流程部署的名称", required =true)@RequestParamString 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")publicclassAuthController{}@Tag(name ="05 历史", description ="历史 API")publicclassHistoryController{}@Tag(name ="02 流程定义", description ="流程定义 API")publicclassProcessDefinitionController{}@Tag(name ="03 流程实例", description ="流程实例 API")publicclassProcessInstanceController{}@Tag(name ="04 任务", description ="任务 API")publicclassTaskController{}

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 的配合，后续再说~

6 传送门

  功夫不负有心人，😁springdoc 和 SpringSecurity 的结合，我也研究好了，文档链接如下 02_学习springdoc与SpringSecurity配合_使用访问令牌来认证

  感谢阅读~