springdoc-openapi is on Open Collective. If you ❤️ this project consider becoming a sponsor.

This project is sponsored by

Table of Contents

• Full documentation
• Security contact information
• Versioning
• Introduction
• Getting Started
  • Library for springdoc-openapi integration with spring-boot and swagger-ui
  • Spring-boot with OpenAPI Demo applications.
    • Source Code for Demo Applications.
    • Demo Spring Boot 4 Web MVC with OpenAPI 3.
    • Demo Spring Boot 4 WebFlux with OpenAPI 3.
    • Demo Spring Boot 4 WebFlux with Functional endpoints OpenAPI 3.
    • Demo Spring Boot 4 and Spring Hateoas with OpenAPI 3.
  • Integration of the library in a Spring Boot 4.x project without the swagger-ui:
  • Error Handling for REST using @ControllerAdvice
  • Adding API Information and Security documentation
  • spring-webflux support with Annotated Controllers
  • Using a separate management port (Spring Boot 4)
  • When Spring Security is enabled
• Acknowledgements
  • Contributors
  • Additional Support

Full documentation

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

Versioning

springdoc-openapi follows Semantic Versioning. MAJOR version increments are released in lockstep with Spring Boot MAJOR releases and may include incompatible/breaking changes. MINOR and PATCH releases follow standard SemVer conventions for backwards-compatible features and fixes, respectively. See CHANGELOG.md for the full release history.

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.

The library automatically generates documentation in JSON/YAML and HTML formatted pages. The generated documentation can be complemented using swagger-api annotations.

This library supports:

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

The following video introduces the Library:

• https://youtu.be/utRxyPfFlDw

For Spring-boot v4 support, make sure you use springdoc-openapi v3

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 4.x application
• Documentation will be available in HTML format, using the official swagger-ui jars.
• The Swagger UI page should then be available at http://server: port/context-path/swagger-ui.html and the OpenAPI description will be available at the following url for json format: http://server:port/context-path/v3/api-docs
  • server: The server name or IP
  • port: The server port
  • context-path: The context path of the application
• Documentation can be available in yaml format as well, on the following path: /v3/api-docs.yaml
• Add the springdoc-openapi-ui library to the list of your project dependencies (No additional configuration is needed):

Maven

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>last-release-version</version>
   </dependency>

Gradle

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

• This step is optional: For custom path of the swagger documentation in HTML format, add a custom springdoc property, in your spring-boot configuration file:

# 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 4 Web MVC with OpenAPI 3.

Demo Spring Boot 4 WebFlux with OpenAPI 3.

Demo Spring Boot 4 WebFlux with Functional endpoints OpenAPI 3.

Demo Spring Boot 4 and Spring Cloud Function Web MVC.

Demo Spring Boot 4 and Spring Cloud Function WebFlux.

Demo Spring Boot 4 and Spring Cloud Gateway.

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

• Documentation will be available at the following url for json format: http://server: port/context-path/v3/api-docs
  • server: The server name or IP
  • port: The server port
  • context-path: The context path of the application
• Documentation will be available in yaml format as well, on the following path : /v3/api-docs.yaml
• Add the library to the list of your project dependencies. (No additional configuration is needed)

Maven

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
      <version>last-release-version</version>
   </dependency>

Gradle

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

• This step is optional: For custom path of the OpenAPI documentation in Json format, add a custom springdoc property, in your spring-boot configuration file:

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

• This step is optional: If you want to disable springdoc-openapi endpoints, add a custom springdoc property, in your spring-boot configuration file:

# 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