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

:

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

Create a Swagger configuration class:

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

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:

<code>@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
}
</code>

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

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

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.