Integrating Swagger (Springfox) 3.0.0 with Spring Boot for Automatic API Documentation

Swagger is an open‑source tool built on the OpenAPI Specification that helps design, build, document, and consume REST APIs. Springfox provides Spring‑Boot integration for Swagger, allowing automatic generation of API documentation from controller annotations.

Resources

Swagger official site: swagger.io

Springfox official site: springfox

Springfox GitHub: springfox/springfox

Springfox demos: springfox/springfox-demos

Maven repository: io.springfox

Swagger Overview

Swagger uses the OpenAPI Specification (OAS) to describe API endpoints, request methods, parameters, and headers, typically written in YAML and transmitted as JSON.

Swagger consists of three main components:

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

Swagger UI – renders the spec as an interactive documentation page.

Swagger Codegen – generates server stubs and client SDKs from the spec.

Springfox Overview

Springfox evolved from the original swagger‑springmvc component to integrate Swagger with Spring MVC. In a Spring Boot project you typically add two dependencies:

springfox-swagger2

springfox-swagger-ui

These generate JSON API docs and provide a UI for browsing them.

Springfox 3.0.0 Release

Removes explicit dependencies on springfox-swagger2 and any @EnableSwagger2 annotations.

Adds the springfox-boot-starter dependency for zero‑configuration support.

Drops Guava and other third‑party libraries (still depends on spring‑plugin and OpenAPI libraries).

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

Provides OpenAPI 3.0.3 compatibility and many new configuration properties.

Compatibility

Java 8+

Spring 5.x

Spring Boot 2.2 or higher

To enable Swagger in Spring Boot, add the @EnableOpenApi annotation to the main class and remove any old SwaggerConfig files.

Access the UI at http://localhost:8080/swagger-ui/index.html (for 2.x versions use /swagger-ui.html ).

Integration Steps

Add the starter dependency to your pom.xml :

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

Configure Swagger properties in application.yml :

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 demo
  try-host: http://localhost:${server.port}

Create a configuration class:

@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)
                .enable(swaggerProperties.getEnable())
                .apiInfo(apiInfo())
                .host(swaggerProperties.getTryHost())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .protocols(newHashSet("https", "http"))
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    // ... apiInfo(), securitySchemes(), securityContexts(), newHashSet() implementations ...
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // exclude swagger resources from other interceptors
    }
}

Define a SwaggerProperties class annotated with @ConfigurationProperties("swagger") to bind the YAML values.

Common Swagger annotations used on controllers and models include:

@Api – describe a controller.

@ApiOperation – describe an endpoint method.

@ApiModel – describe a model class.

@ApiModelProperty – describe model fields.

@ApiImplicitParams – describe method parameters.

@ApiResponses – describe possible responses.

@ApiIgnore – exclude an endpoint from documentation.

The article also provides a complete demo project and screenshots of the generated documentation UI.