Integrating Swagger with Spring Boot Using Springfox 3.0.0

For REST APIs, documentation is crucial; Swagger offers a way to generate documentation automatically from code and annotations, ensuring timely API docs.

Swagger is an open‑source tool built on the OpenAPI Specification (OAS) that helps design, build, record, and consume REST APIs. The specification is usually written in YAML and transmitted as JSON.

Swagger consists of three main components:

Swagger Editor – a browser‑based editor for writing OpenAPI specifications.

Swagger UI – renders the specification as an interactive API documentation page.

Swagger Codegen – generates server stubs and client SDKs from an OpenAPI definition.

Springfox is the evolution of the original swagger‑springmvc component created by Marty Pitt to integrate Swagger into Spring MVC projects. In modern Spring Boot applications, two dependencies are typically required:

springfox‑swagger2

springfox‑swagger‑ui

Springfox 3.0.0, the latest release, removes explicit dependencies on springfox‑swagger2 and any @EnableSwagger2 annotations, introducing the springfox‑boot‑starter dependency for zero‑configuration support. New features include:

Removal of explicit springfox‑swagger2 dependencies.

Removal of @EnableSwagger2 annotations.

Addition of the springfox‑boot‑starter dependency.

Reduced reliance on third‑party libraries (only spring‑plugin and OpenAPI libraries remain).

Support for Spring 5, WebFlux (request mapping only), Spring Integration, and Spring Boot 2.2+.

Support for OpenAPI 3.0.3 and improved spec compatibility.

Compatibility notes: Java 8+, Spring 5.x, and Spring Boot 2.2+ are required.

To enable Swagger in a Spring Boot project, add the @EnableOpenApi annotation to the main application class and remove any previous SwaggerConfig.java files.

Integration steps:

Add the Maven dependency:

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

Configure application.yml with Swagger properties (enable flag, application name, version, description, host, etc.).

spring:
  application:
    name: springfox-swagger
server:
  port: 8080
swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: 1.0
  application-description: springfox swagger 3.0 integration demo
  try-host: http://localhost:${server.port}

Create a configuration class annotated with @EnableOpenApi and @Configuration that implements WebMvcConfigurer . The class should inject SwaggerProperties , define a Docket bean, set API info, security schemes, and globally exclude Swagger paths from other interceptors.

@EnableOpenApi
@Configuration
public class SwaggerConfiguration implements WebMvcConfigurer {
    private final SwaggerProperties swaggerProperties;
    public SwaggerConfiguration(SwaggerProperties swaggerProperties) {
        this.swaggerProperties = swaggerProperties;
    }
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
            .pathMapping("/")
            .enable(swaggerProperties.getEnable())
            .apiInfo(apiInfo())
            .host(swaggerProperties.getTryHost())
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .protocols(newHashSet("https", "http"))
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
    }
    // ... other helper methods omitted for brevity ...
}

Common Swagger annotations used in controllers include:

@Api – describes the controller class.

@ApiOperation – describes a specific endpoint method.

@ApiModel and @ApiModelProperty – describe request/response objects.

@ApiImplicitParams – documents method parameters.

@ApiResponses – documents possible responses.

@ApiIgnore – excludes a method from documentation.

A complete demo project named springfox-swagger showcases the configuration and produces an interactive UI accessible at http://localhost:8080/swagger-ui/index.html (for version 2.x the URL is /swagger-ui.html ).

References:

Using Swagger in Spring Boot projects.

Springfox 3.0.0 (including springfox‑swagger2‑3.0.0 ) integration with OpenAPI 3.