文章目录

• 1 什么是 springdoc ?
• 2 springdoc 基本信息
• 3 maven 依赖
• • 3.1 version 1.7.0 及之前
  • 3.2 新的 version 2.x 及之后
  • 4 正文来袭
  • • 4.1 给 Controller 加注解
    • 4.2 给 Model 加注解
    • 4.3 需要上传附件怎么办?
    • • 4.3.1 错误写法
      • 4.3.2 正确写法
      • 4.4 如何给 API 排序? 如何给 HTTP 方法排序?
      • • 4.4.1 API 排序示例
        • 4.4.2 HTTP 方法排序示例
        • 5 大功告成
        • 6 传送门

          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个依赖：

          
          
              org.springdoc
              springdoc-openapi-ui
              1.6.14
          
          
          
              org.springdoc
              springdoc-openapi-security
              1.6.14
          
          

            关于 springdoc 配合 spring security 的知识，目前的我对此一无所知🤣。后面再研究它吧，先把基础操作弄明白 已经搞定啦，详见文末链接。

            可以从 https://mvnrepository.com/ 里面查询到最新版，然后把 1.6.14 换成最新的。

          3.2 新的 version 2.x 及之后

            目前（2023年10月）最新的版本 version 2.2.0，支持的是 SpringBoot 3.x 和 Java 17，此时只需需要引入一个依赖：

          
          
             org.springdoc
             springdoc-openapi-starter-webmvc-ui
             2.2.0
          
          
          
             org.springdoc
             springdoc-openapi-starter-webflux-ui
             2.2.0
          
          

            mvc 和 webflux 的依赖，2选1就可以。它们俩的版本号是一致的。新版本 2.x 的注解，和 1.x 的一样。

          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 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 = "")
              private String xml;
              @Schema(description = "流程部署名称", example = "请假流程")
              private String deployName;
          }
          @Schema(description = "json结构的响应")
          public class JsonResult {
              @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 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 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 的配合，后续再说~

            6 传送门

            1. 功夫不负有心人，😁springdoc 和 SpringSecurity 的结合，我也研究好了，文档链接如下 《02_学习springdoc与SpringSecurity配合_使用访问令牌来认证》
            2. springdoc 与微服务的结合，文档链接如下 《03_学习springdoc与微服务结合_简述》
            3. springdoc 与 oauth2 结合，文档链接如下 《04_学习springdoc与oauth结合_简述》

              感谢阅读~

             
             长沙网站制作策划  长沙建网站  怎么搭建自己的网站  网站设计基础教程  免费空间申请  保定网络运营公司