An extended support for *springdoc-openapi v1*
project is now available for organizations that need support beyond 2023.

For more details, feel free to reach
out: [[email protected]](mailto:[email protected])

This project is sponsored by

  

Table of Contents

• [Full documentation](#full-documentation)
• [Introduction](#introduction)
• [Getting Started](#getting-started)

• [Acknowledgements](#acknowledgements)

Full documentation

Introduction

The springdoc-openapi Java library helps automating the generation of API documentation
using Spring Boot projects.
springdoc-openapi works by examining an application at runtime to infer API semantics
based on Spring configurations, class structure and various annotations.

This library supports:

• OpenAPI 3
• Spring-boot v3 (Java 17 & Jakarta EE 9)
• JSR-303, specifically for @NotNull, @Min, @Max, and @Size.
• Swagger-ui
• OAuth 2
• GraalVM native images

• https://youtu.be/utRxyPfFlDw

This is a community-based project, not maintained by the Spring Framework Contributors (
Pivotal)

Getting Started

Library for springdoc-openapi integration with spring-boot and swagger-ui

• Automatically deploys swagger-ui to a Spring Boot 3.x application
• Documentation will be available in HTML format, using the

• The Swagger UI page should then be available at

• Documentation can be available in yaml format as well, on the following path:

Maven

xml
   
      org.springdoc
      springdoc-openapi-starter-webmvc-ui
      last-release-version

Gradle

groovy
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:latest'

• This step is optional: For custom path of the swagger documentation in HTML format, add

properties
# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

Spring-boot with OpenAPI Demo applications.

Source Code for Demo Applications.

Demo Spring Boot 3 Web MVC with OpenAPI 3.

Demo Spring Boot 3 WebFlux with OpenAPI 3.

Demo Spring Boot 3 WebFlux with Functional endpoints OpenAPI 3.

Demo Spring Boot 3 and Spring Cloud Function Web MVC.

Demo Spring Boot 3 and Spring Cloud Function WebFlux.

Demo Spring Boot 3 and Spring Cloud Gateway.

!Branching

Integration of the library in a Spring Boot 3.x project without the swagger-ui:

• Documentation will be available at the following url for JSON format: http://server:

• Documentation will be available in yaml format as well, on the following

• Add the library to the list of your project dependencies. (No additional configuration

Maven

xml
   
      org.springdoc
      springdoc-openapi-starter-webmvc-api
      last-release-version

Gradle

groovy
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-api:latest'

• This step is optional: For custom path of the OpenAPI documentation in Json format, add

properties
# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs

properties
# disable api-docs
springdoc.api-docs.enabled=false

Error Handling for REST using @ControllerAdvice

To generate documentation automatically, make sure all the methods declare the HTTP Code
responses using the annotation: @ResponseStatus.

Adding API Information and Security documentation

spring-webflux support with Annotated Controllers

• Documentation can be available in yaml format as well, on the following path :

• Add the library to the list of your project dependencies (No additional configuration

Maven

xml
   
      org.springdoc
      springdoc-openapi-starter-webflux-ui
      last-release-version

Gradle

groovy
implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:latest'

• This step is optional: For custom path of the swagger documentation in HTML format, add

properties
# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

Releases:

• https://central.sonatype.com/search?q=g:org.springdoc

Snapshots:

• https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/org/springdoc/

Using a separate management port (Spring Boot 3)

Some Spring Boot apps run Actuator on a separate management port. In that case:

yaml
server:
  port: 8080

management:
  server:
    port: 9090
  endpoints:
    web:
      exposure:
        include: health,info

# springdoc is enabled by default with the starter;
# endpoints remain on the application port.
# (OpenAPI JSON = /v3/api-docs, Swagger UI = /swagger-ui/index.html)

When Spring Security is enabled