Repository files navigation

IMPORTANT:springdoc-openapi v1.8.0 is the latest Open Source release supporting Spring Boot 2.x and 1.x.

An extended support forspringdoc-openapi v1project is now available for organizations that need support beyond 2023.

For more details, feel free to reach out:sales@springdoc.org

springdoc-openapi is onOpen Collective. If you ❤️ this project consider becoming asponsor.

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.
    • Source Code for Demo Applications.
    • Demo Spring Boot 2 Web MVC with OpenAPI 3.
    • Demo Spring Boot 2 WebFlux with OpenAPI 3.
    • Demo Spring Boot 2 WebFlux with Functional endpoints OpenAPI 3.
    • Demo Spring Boot 2 and Spring Hateoas with OpenAPI 3.
  • 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
  • Contributors
  • Additional Support

The springdoc-openapi Java library helps automating the generation of API documentationusing Spring Boot projects.springdoc-openapi works by examining an application at runtime to infer API semanticsbased 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 usingswagger-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:

• https://youtu.be/utRxyPfFlDw

Forspring-boot v3 support, make sure you usespringdoc-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 theofficialswagger-ui jars.
• The Swagger UI page should then be available athttp://server:port/context-path/swagger-ui.html and the OpenAPI description will be available at thefollowing 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 thespringdoc-openapi-ui library to the list of your project dependencies (Noadditional 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, adda custom springdoc property, in your spring-boot configuration file:

# swagger-ui custom pathspringdoc.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 IP
  • port: The server port
  • context-path: The context path of the application
• Documentation will be available in yaml format as well, on the followingpath :/v3/api-docs.yaml
• Add the library to the list of your project dependencies. (No additional configurationis 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, adda custom springdoc property, in your spring-boot configuration file:

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

• This step is optional: If you want to disablespringdoc-openapi endpoints, add acustom springdoc property, in yourspring-boot configuration file:

# disable api-docsspringdoc.api-docs.enabled=false

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

The library uses spring-boot application auto-configured packages to scan for thefollowing 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@OpenAPIDefinitionand@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 configurationis 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, adda custom springdoc property, in your spring-boot configuration file:

# swagger-ui custom pathspringdoc.swagger-ui.path=/swagger-ui.html

Thespringdoc-openapi libraries are hosted on maven central repository.The artifacts can be viewed accessed at the following locations:

Releases:

• https://s01.oss.sonatype.org/content/groups/public/org/springdoc/.

Snapshots:

• https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/.

springdoc-openapi is relevant and updated regularly due to the valuable contributions fromitscontributors.

Thanks you all for your support!

• Spring Team - Thanks for their support by sharing all relevantresources around Spring projects.
• JetBrains - Thanks a lot forsupporting springdoc-openapi project.