IMPORTANT: springdoc-openapi v1.8.0 is the latest Open Source release supporting Spring Boot 2.x and 1.x.
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]
springdoc-openapi is on Open Collective. If you ❤️ this project consider becoming
a sponsor.
This project is sponsored by
- Full documentation
- Introduction
- Getting Started
- Library for springdoc-openapi integration with spring-boot and swagger-ui
- Spring-boot with OpenAPI Demo applications.
- Integration of the library in a Spring Boot 3.x project without the swagger-ui:
- Error Handling for REST using @ControllerAdvice
- Adding API Information and Security documentation
- spring-webflux support with Annotated Controllers
- Acknowledgements
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 v3 (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:
For spring-boot v3 support, make sure you use springdoc-openapi v2
This is a community-based project, not maintained by the Spring Framework Contributors (Pivotal)
- Automatically deploys swagger-ui to a Spring Boot 3.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 IPport: The server portcontext-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-uilibrary 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
- Documentation will be available at the following url for json format: http://server:
port/context-path/v3/api-docs
server: The server name or IPport: The server portcontext-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-openapiendpoints, add a custom springdoc property, in yourspring-bootconfiguration file:
# disable api-docs
springdoc.api-docs.enabled=falseTo generate documentation automatically, make sure all the methods declare the HTTP Code responses using the annotation: @ResponseStatus.
The library uses spring-boot application auto-configured packages to scan for the
following annotations in spring beans: OpenAPIDefinition and Info.
These annotations declare, API Information: Title, version, licence, security, servers,
tags, security and externalDocs.
For better performance of documentation generation, declare @OpenAPIDefinition
and @SecurityScheme annotations within a Spring managed bean.
- Documentation can 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-webflux-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.htmlThe springdoc-openapi libraries are hosted on maven central repository.
The artifacts can be viewed accessed at the following locations:
Releases:
Snapshots:
springdoc-openapi is relevant and updated regularly due to the valuable contributions from its contributors.
Thanks you all for your support!
- Spring Team - Thanks for their support by sharing all relevant resources around Spring projects.
- JetBrains - Thanks a lot for supporting springdoc-openapi project.
