Master Springdoc-OpenAPI: Generate OpenAPI 3 Docs & Swagger UI for Spring Boot

1. Overview

Company is organizing project documentation; for building REST APIs the documentation is crucial. This article introduces Spring Doc, a tool based on the OpenAPI 3 specification that simplifies generation and maintenance of API documentation for Spring Boot 1.x and 2.x applications.

2. Set up springdoc-openapi

Add the springdoc-openapi-core dependency to pom.xml:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-core</artifactId>
    <version>1.1.45</version>
</dependency>

After starting the application, the default documentation is available at /v3/api-docs. To customize the path, set springdoc.api-docs.path in application.properties, e.g., springdoc.api-docs.path=/api-docs, which makes the docs reachable at http://localhost:8080/api-docs/. The YAML version can be accessed via /api-docs.yaml.

3. Integrate springdoc-openapi with Swagger UI

3.1 Maven dependency

Add the springdoc-openapi-ui dependency:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.45</version>
</dependency>

Access the Swagger UI at http://localhost:8080/swagger-ui.html. The path can be customized with springdoc.swagger-ui.path, e.g., springdoc.swagger-ui.path=/swagger-ui-custom.html.

3.2 Example controller

@RestController
@RequestMapping("/api/ball")
public class BallController {
    @Autowired
    private BallRepository repository;

    @GetMapping("/{id}")
    public Ball findById(@PathVariable long id) {
        return repository.findById(id)
            .orElseThrow(() -> new BallNotFoundException());
    }

    @GetMapping("/")
    public Collection<Book> findBooks() {
        return repository.getBooks();
    }

    @PutMapping("/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Book updateBook(@PathVariable("id") final String id, @RequestBody final Book book) {
        return book;
    }
}

Visit the custom Swagger UI page, e.g., http://localhost:8080/swagger-ui-custom.html.

4. springdoc-openapi with Spring WebFlux

Add the springdoc-openapi-webflux-ui dependency:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webflux-ui</artifactId>
    <version>1.1.45</version>
</dependency>

Access the UI at http://localhost:8080/swagger-ui.html or customize the path similarly.

5. Use springdoc-openapi Maven plugin

Add the plugin configuration to pom.xml to generate JSON or YAML OpenAPI files during the integration-test phase:

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>0.2</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
        <outputFileName>openapi.json</outputFileName>
        <outputDir>${project.build.directory}</outputDir>
    </configuration>
</plugin>

6. Generate documentation from JSR‑303 Bean Validation

Annotations such as @NotNull, @NotBlank, @Size, @Min, @Max on model fields are reflected in the generated OpenAPI schema. Example:

public class Ball {
    private long id;
    @NotBlank
    @Size(min = 0, max = 20)
    private String title;
    @NotBlank
    @Size(min = 0, max = 30)
    private String author;
}

7. Document error responses with @ControllerAdvice

Methods annotated with @ResponseStatus inside a @RestControllerAdvice class are included in the OpenAPI spec. Example:

@RestControllerAdvice
public class GlobalControllerExceptionHandler {
    @ExceptionHandler(ConversionFailedException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ResponseEntity<String> handleConversion(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(BallNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ResponseEntity<String> handleBallNotFound(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

8. Summary

Spring Boot 2.2.x may not be fully supported; the article uses Spring Boot 2.1.8.RELEASE. The complete source code is available on GitHub.