01

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 = "接口请求成功"))
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());
    }
}

  启动项目后效果如下图

图1 总览

图2 第一个接口

图3 第二个接口

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 可以看到如下图的内容

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

5 大功告成

  springdoc 的基本使用到这里就全部欧克了so easy ~

  至于它和 spring security 的配合后续再说~

  感谢阅读~