Simplify Spring Boot API Docs with Springfox 3.0.0 Starter and Security Integration

Previously Swagger integration used springfox-swagger and springfox-swagger-ui jars. Springfox 3.0.0 provides a Spring Boot starter that simplifies the setup.

Using the official starter

Add the springfox-boot-starter dependency to pom.xml:

<!--springfox swagger official Starter-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Create a Swagger configuration class:

@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI Demo")
                .description("mall-tiny")
                .contact(new Contact("macro", null, null))
                .version("1.0")
                .build();
    }
}

Access the API docs at http://localhost:8088/swagger-ui/.

Differences from previous versions

The old version required springfox-swagger2 and springfox-swagger-ui plus additional dependencies such as swagger-models and swagger-annotations, often causing NumberFormatException. The new starter removes these extra jars, eliminates the need for guava, and changes the UI path to /swagger-ui/ (previously /swagger-ui.html). It also adds the springfox.documentation.enabled property to enable or disable Swagger generation per environment.

Integrating with Spring Security

To protect APIs, add a security scheme that sends an Authorization header:

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    // apiInfo, securitySchemes, securityContexts, getContextByPath, defaultAuth methods as in source
}

Configure Spring Security to allow unauthenticated access to Swagger static resources:

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
            .authorizeRequests()
            .antMatchers(HttpMethod.GET,
                "/", "/swagger-ui/", "/*.html", "/favicon.ico",
                "/**/*.html", "/**/*.css", "/**/*.js",
                "/swagger-resources/**", "/v2/api-docs/**")
            .permitAll()
            .antMatchers("/admin/login").permitAll()
            .antMatchers(HttpMethod.OPTIONS).permitAll()
            .anyRequest().authenticated();
    }
}

After obtaining a JWT token (e.g., using admin:123456), click the “Authorize” button in Swagger UI, enter the Authorization header, and you can call protected endpoints.

The official Springfox starter resolves many previous integration issues, streamlines Swagger setup in Spring Boot, and retains compatibility with existing configurations.