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

IMPORTANT:

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

Table of Contents

• 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

Full documentation

Introduction

• := Java library /

  • based on Spring Boot projects -- automate the generation of -- API documentation in format
    • JSON/YAML
    • HTML
  • how does it work?
    • infer API semantics -- based on -- examine an application at runtime
      • Spring configurations
        • ❌NOT ❌in placing OpenAPI specificaton in the classpath -- Example --
      • class structure
      • various annotations
    • +swagger-api annotations

• 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

  • introductory video

• For spring-boot v3 support -> use springdoc-openapi v2

• community-based project / NOT maintained by the Spring Framework Contributors (Pivotal)

Getting Started

springdoc-openapi -- integrated with -- spring-boot and swagger-ui

• Swagger-ui
  • -- is automatically deployed to -- a Spring Boot 3.x application
  • page at "http://server:port/context-path/swagger-ui.html"
    • server: server name or IP
    • port: server port
    • context-path: context path of the application
• Documentation -- using the official swagger-ui jars -- is available in
  • HTML format
  • .yaml at "http://server:port/context-path/v3/api-docs.yaml"
• OpenAPI description (.json) at "http://server:port/context-path/v3/api-docs"
• How to set up?
  • Add the springdoc-openapi-ui library to the list of your project dependencies

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

  • if you want to customize the path of the swagger documentation in HTML format -> , add 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 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.

---

springdoc-openapi -- integrated with -- Spring Boot 3.x BUT without swagger-ui

• Documentation
  • at 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
  • at yaml format: "http://server:port/context-path/v3/api-docs.yaml"
• How to set up?
  • add to your project dependencies

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

  • if you want to customize the path of the OpenAPI documentation in Json format -> add in your spring-boot configuration file

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

  • if you want to disable springdoc-openapi endpoints -> add in your spring-boot configuration file:

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

Error Handling for REST -- via -- @ControllerAdvice

• Requirements to generate the documentation
  • 👁️ ALL the methods must declare the HTTP Code responses -- via -- @ResponseStatus 👁️

Adding API Information and Security documentation

• Declare within a 👁️ Spring managed bean 👁️,
  • the annotations
    • @OpenAPIDefinition
    • @SecurityScheme
  • Reason: 🧠 scan the spring-boot application auto-configured packages, looking for beans 🧠
    • OpenAPIDefinition
    • Info

spring-webflux support with Annotated Controllers

• Documentation available in
  • yaml format at "http://server:port/context-path/v3/api-docs.yaml"
• How to set up?
  • add the library

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

  • if you want to customize path of the swagger documentation in HTML format -> add in your spring-boot configuration file

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

Releases and Snapshots

• Releases:
  • https://s01.oss.sonatype.org/content/groups/public/org/springdoc/
• Snapshots:
  • https://s01.oss.sonatype.org/content/repositories/snapshots/org/springdoc/