Master Swagger 3.0 Integration with Spring Boot: Step‑by‑Step Guide

Overview

Swagger 3.0 (Springfox) is hosted at https://github.com/springfox/springfox. The migration from Swagger 2 to 3 removes the springfox-swagger2 dependency, deletes all @EnableSwagger2 annotations, adds the springfox-boot-starter dependency, drops third‑party libraries such as guava, and changes the UI URL to http://<ip>:<port>/project/swagger-ui/index.html.

Spring Boot version

The example uses Spring Boot 2.3.5.RELEASE.

Adding the dependency

Include the starter in pom.xml:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

What the starter does

The starter registers OpenApiAutoConfiguration via /META-INF/spring.factories. This auto‑configuration imports several configuration classes, most importantly OpenApiDocumentationConfiguration, and enables properties defined in SpringfoxConfigurationProperties. No additional custom logic is executed.

Basic configuration example

Create a configuration class that enables OpenAPI and binds custom properties:

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerConfig {
    @Autowired
    private SwaggerProperties properties;

    @Bean
    public Docket frontApi() {
        return new Docket(DocumentationType.OAS_30)
                .enable(properties.getFront().getEnable())
                .groupName(properties.getFront().getGroupName())
                .apiInfo(frontApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo frontApiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getFront().getTitle())
                .description(properties.getFront().getDescription())
                .version(properties.getFront().getVersion())
                .contact(new Contact(
                        properties.getFront().getContactName(),
                        properties.getFront().getContactUrl(),
                        properties.getFront().getContactEmail()))
                .build();
    }
}

The @EnableOpenApi annotation imports OpenApiDocumentationConfiguration, which activates Swagger support.

API grouping

Define multiple Docket beans, each with a distinct groupName(), to separate front‑end, back‑end, app, or mini‑program APIs. Example for a back‑end group:

@Bean
public Docket backApi() {
    return new Docket(DocumentationType.OAS_30)
            .enable(properties.getBack().getEnable())
            .groupName("后台管理")
            .apiInfo(backApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage(properties.getBack().getBasePackage()))
            .paths(PathSelectors.any())
            .build();
}

Adding authorization information

Configure a global token header by adding securitySchemes() and securityContexts() to the Docket bean:

@Bean
public Docket frontApi() {
    // other builder calls …
    .securitySchemes(securitySchemes())
    .securityContexts(securityContexts());
}

private List<SecurityScheme> securitySchemes() {
    ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
    return Collections.singletonList(apiKey);
}

private List<SecurityContext> securityContexts() {
    return Collections.singletonList(
        SecurityContext.builder()
            .securityReferences(Collections.singletonList(
                new SecurityReference("BASE_TOKEN",
                    new AuthorizationScope[]{new AuthorizationScope("global", "")})))
            .build());
}

After this configuration the Swagger UI shows an “Authorize” button to input the token.

Adding global request parameters

Common headers (e.g., platform) can be added via globalRequestParameters():

@Bean
public Docket frontApi() {
    RequestParameter parameter = new RequestParameterBuilder()
            .name("platform")
            .description("请求的平台")
            .in(ParameterType.HEADER)
            .required(true)
            .build();
    List<RequestParameter> parameters = Collections.singletonList(parameter);
    return new Docket(DocumentationType.OAS_30)
            // other builder calls …
            .globalRequestParameters(parameters);
}

Potential configuration redundancy

The auto‑configuration class OpenApiAutoConfiguration already imports OpenApiDocumentationConfiguration. The @EnableOpenApi annotation also imports the same configuration. Tests show that Swagger works even when @EnableOpenApi is omitted, suggesting that the annotation may be redundant in a Spring Boot environment that includes the starter.

Summary: This guide demonstrates how to integrate Swagger 3.0 with Spring Boot 2.3.5, covering dependency setup, the role of springfox-boot-starter , basic and grouped API documentation, global authorization headers, common request parameters, and a note on a possible configuration redundancy.