SpringBoot升级swagger3

Edited on In ,

从 SpringFox 迁移

依赖替换

移除所有 swagger2 依赖，添加 springdoc

1
2
3
4
5
6

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

注解替换

swagger3 注解包是 io.swagger.v3.oas.annotations.

  • @Api → @Tag
  • @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
  • @ApiImplicitParam → @Parameter
  • @ApiImplicitParams → @Parameters
  • @ApiModel → @Schema
  • @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
  • @ApiModelProperty → @Schema
  • @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
  • @ApiParam → @Parameter
  • @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

Java 集成

Before:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public class SwaggerConfig {

    @Bean
    public Docket publicApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
                .paths(PathSelectors.regex("/public.*"))
                .build()
                .groupName("springshop-public")
                .apiInfo(apiInfo());
    }

    @Bean
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
                .paths(PathSelectors.regex("/admin.*"))
                .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
                .build()
                .groupName("springshop-admin")
                .apiInfo(apiInfo());
    }
}

Now:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("springshop-public")
                .pathsToMatch("/public/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("springshop-admin")
                .pathsToMatch("/admin/**")
                .addMethodFilter(method -> method.isAnnotationPresent(Admin.class))
                .build();
    }

    /**
     * 根据接口扫描
     */
    @Bean
    public GroupedOpenApi demoApi() {
        String[] paths = {"/demo/**"};
        return GroupedOpenApi.builder()
                .group("demo")
                .pathsToMatch(paths)
                .build();
    }

    /**
     * 根据parent package 扫描
     */
    @Bean
    public GroupedOpenApi maxzhaoApi() {
        return GroupedOpenApi.builder()
                .group("maxzhao")
                .packagesToScan("com.maxzhao")
                .build();
    }
}

If you have only one Docket — remove it and instead add properties to your application.properties:

1
2
springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**
  • Add bean of OpenAPI type. See example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
public class SwaggerConfig {
    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Swagger3 API")
                        .description("Spring swagger3 sample application")
                        .version("v0.0.1")
                        .contact(new Contact()
                                .name("maxzhao")
                                .url("https://maxzhao-it.github.io/blog/")
                                .email("1441439636@qq.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("maxzhao Documentation")
                        .url("https://maxzhao-it.github.io/blog/"));
    }
}

本文地址： https://github.com/maxzhao-it/blog/post/582c1911/