SpringDoc 的基本使用

2167人浏览 / 2人评论

参考

01_学习springdoc的基本使用_小匠石钧知的博客-CSDN博客

02_学习springdoc与SpringSecurity配合_使用访问令牌来认证_小匠石钧知的博客-CSDN博客

注解文档：https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations

SpringDoc 简介

springdoc 的底层是 swagger3，前端页面看起来和 swagger2 的差不多。

swagger2 遵循的是 OpenAPI 2 规范。现在已经有了 OpenAPI 3 规范，springdoc 便是 OpenAPI 3 和 springboot 的结合，是 springfox 的完美替代品。

官网：https://springdoc.org/

Maven 依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.3</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<!-- 如果你的项目里面使用到了 spring security 的话， 需要加上springdoc 配合 spring security 的依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
</dependency>

使用注解

Controller 注解

@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());
    }
}

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;
    // 省略部分内容
}

上传文件

@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);
}

给 API（controller 类）和 HTTP 方法（controller 类中的方法）排序

配置项

springdoc.swagger-ui.tagsSorter 给 API 排序，如果其值为 alpha 就表示按字母顺序排序。默认情况下（也就是不配置此项），API 的顺序由 swagger 自己决定（也就是没什么顺序）；
springdoc.swagger-ui.operationsSorter 给 HTTP 方法排序，其值为 alpha 同样表示按字母顺序排序，值为 method 表示根据 HTTP 请求的类型（顺序如下：DELETE > GET > POST > PUT）排序。默认情况下，Controller 代码里面，你写的是什么顺序，swagger 就给你展示什么顺序。

示例

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:
    tags-sorter: alpha # tag sort
    operations-sorter: method # operation sort

结合 Spring Security

@Configuration
public class SpringDocConfig {
    // 文档访问路径 /swagger-ui/index.html
    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI()
                .components(new Components()
                        // Set spring security jwt accessToken's Authenticated request header: Authorization: Bearer xxx.xxx.xxx
                        .addSecuritySchemes("authScheme", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .bearerFormat("JWT")
                                .scheme("bearer")))
                // Set some titles
                .info(new Info()
                        .title("spring-data-jpa 的 API")
                        .version("1.0.0")
                        .description("加油↖(^ω^)↗")
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0")));
    }
}