SpringBoot整合OpenAPI3

文档：https://springdoc.org
示例：https://github.com/springdoc/springdoc-openapi#demo-spring-boot-2-web-mvc-with-openapi-3

1. 依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.2</version>
</dependency>

2. 配置

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("springbootdemo-public")
                .pathsToMatch("/public/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("springbootdemo-admin")
                .pathsToMatch("/admin/**")
                .build();
    }

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(info())
//                .externalDocs(externalDocumentation())
                .components(components())
                .security(Lists.newArrayList(new SecurityRequirement().addList("Authorization")));
    }

    private ExternalDocumentation externalDocumentation() {
        return new ExternalDocumentation()
                .description("SpringShop Wiki Documentation")
                .url("https://springshop.wiki.github.org/docs");
    }

    private Components components() {
        return new Components()
                .addSecuritySchemes("Authorization", new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT"));
    }

    private Info info() {
        return new Info()
                .title("springbootdemoAPI")
                .description("springbootdemoAPI相关文档")
                .version("v1.0")
                .contact(new Contact()
                        .name("开心")
                        .url("https://blog.ckx.ink")
                        .email("chenkaixin12121@163.com"))
                .license(new License()
                        .name("Apache 2.0")
                        .url("https://opensource.org/licenses/Apache2.0"));
    }
}

springdoc:
  api-docs:
    enabled: true
    path: /api-docs
  swagger-ui:
    enabled: true
    path: /doc.html
    display-request-duration: true
    groups-order: DESC
    operationsSorter: method
    disable-swagger-default-url: true
    use-root-path: true

3. 测试

@Data
@Schema(description = "用户信息")
public class User {

    @Schema(description = "用户名", required = true, minLength = 6, maxLength = 20)
    private String username;

    @Schema(description = "密码", required = true, minLength = 6, maxLength = 20)
    private String password;

    @Schema(description = "是否删除", hidden = true, allowableValues = {"0", "1"})
    private Integer isDel;
}

@Tag(name = "admin", description = "管理接口")
@RestController
@RequestMapping("/admin")
public class AdminController {

    @Operation(summary = "测试方法")
    @GetMapping(value = "/sayHello")
    public String sayHello(@Parameter(description = "名称", in = ParameterIn.QUERY) @RequestParam(required = false, defaultValue = "chenkaixin12121") String name) {
        return "hello " + name;
    }

    @Operation(summary = "获取当前用户", security = {@SecurityRequirement(name = "Authorization")})
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "请求成功", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = User.class))}),
            @ApiResponse(responseCode = "400", description = "客户端参数错误", content = @Content),
            @ApiResponse(responseCode = "404", description = "请求路径不存在", content = @Content)
    })
    @GetMapping(value = "/getUser")
    public User getUser() {
        User user = new User();
        user.setUsername("chenkaixin12121");
        user.setPassword("123456");
        return user;
    }
}

@Tag(name = "public", description = "公共接口")
@RestController
@RequestMapping("/public")
public class PublicController {

    @Operation(summary = "测试方法")
    @GetMapping(value = "/sayHello")
    public String sayHello(@Parameter(description = "名称", in = ParameterIn.QUERY) @RequestParam(required = false, defaultValue = "chenkaixin12121") String name) {
        return "hello " + name;
    }
}

访问：http://localhost:8080/doc.html