[opensourcedex]

springdoc-openapi is a free, open source api development & testing project written in Java and released under Apache-2.0. It has 3,744 GitHub stars, 611 forks and 14 open issues, and was last pushed 9 days ago. On this registry it ranks #67 of 186 tracked projects in API Development & Testing, with 5 head-to-head comparisons available. It gained 6 stars over the last 30 tracked days.

What is springdoc-openapi?

springdoc-openapi is a Java library, released under the Apache-2.0 licence, that generates OpenAPI 3 documentation for Spring Boot applications by inspecting a running application at runtime, and it is aimed at Java and Kotlin developers building REST APIs who want their API documentation to stay in step with the code they actually ship.

What it is

springdoc-openapi is a library that automates the generation of API documentation for Spring Boot projects. It works by examining an application at runtime and inferring API semantics from Spring configuration, class structure, and the various annotations present on the code. The output is documentation produced in JSON and YAML formats alongside HTML formatted pages, and the result can be complemented with swagger-api annotations where convention-based inference is not enough. The project lives in the Spring ecosystem and tracks it closely: springdoc-openapi follows Semantic Versioning, and MAJOR releases are issued in lockstep with Spring Boot MAJOR releases, which means they may carry incompatible or breaking changes.

The concrete problem it solves is the drift between a hand-maintained API specification and the API that the application actually exposes. Rather than requiring a developer to write and then keep updating a separate OpenAPI specification file by hand, the library derives the specification from the application itself, so the published contract reflects the running code. It supports OpenAPI 3, Spring Boot v4 on Java 17 and Jakarta EE 9, Swagger UI, OAuth 2, JSR-303 validation constraints, and GraalVM native images.

Key capabilities

  • Generates API documentation at runtime by inferring semantics from Spring configuration, class structure, and annotations, with no hand-written specification to maintain.
  • Emits documentation in both JSON and YAML formats, together with HTML formatted pages.
  • Ships Swagger UI integration, and can also be integrated into a Spring Boot project without Swagger UI.
  • Accepts swagger-api annotations to complement the inferred documentation.
  • Maps JSR-303 constraints to the specification, specifically @NotNull, @Min, @Max, and @Size.
  • Supports OpenAPI 3, OAuth 2 security documentation, and applications running with Spring Security enabled.
  • Covers Spring Boot v4 on Java 17 and Jakarta EE 9, Spring WebFlux with annotated controllers, functional endpoints, Spring HATEOAS, Spring Data REST, and GraalVM native images.

Who uses it and how

  • Java teams running Spring Boot 4 Web MVC with annotated controllers, using the library to publish documentation without maintaining a parallel specification.
  • Reactive teams on Spring WebFlux, including those using the functional endpoint style alongside annotated controllers.
  • Teams exposing hypermedia or repository-driven APIs through Spring HATEOAS and Spring Data REST.
  • Teams whose APIs sit behind Spring Security, where they need OAuth 2 and other security requirements reflected in the generated documentation.
  • Teams that want the documentation endpoint on a separate management port, or that deploy as GraalVM native images.

Getting started

The README directs readers to the full documentation at springdoc.org and lists demo applications for Spring Boot 4 Web MVC, WebFlux, WebFlux with functional endpoints, and Spring HATEOAS, each with OpenAPI 3. No Maven or Gradle coordinates, Docker image, or compose file appear in the material provided here.

How it compares

No list of paid products that this project replaces is provided in the facts, and the facts name no comparable tools, so springdoc-openapi stands alone in this registry. Its closest neighbours in the material are swagger-api annotations and Swagger UI, which the README presents as complements to the library rather than alternatives to it.

When to use it — and when not to

This is a library rather than a service, so there is no database, object storage, or SMTP infrastructure to operate; the adoption cost is a dependency inside a Spring Boot application and the configuration that goes with it. Teams not on Spring Boot, or those who want a documentation pipeline with a vendor support contract, are a poor fit, and the versioning policy is worth weighing: MAJOR releases move in lockstep with Spring Boot MAJOR releases and may introduce breaking changes, so upgrades need planning. The README also describes the project as community-based, security vulnerabilities are routed through the Tidelift security contact rather than handled by a vendor, and the excerpt provided is truncated mid-sentence, so the full statement about project maintenance and ownership is not visible here.

project readme (upstream, from github) — read inline

Octocat Build Status Quality Gate Known Vulnerabilities Stack Exchange questions

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

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:

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.

Branching

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 responses using the annotation: @ResponseStatus.

Adding API Information and Security documentation

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.

spring-webflux support with Annotated Controllers

  • 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-webflux-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

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

Releases:

Snapshots:

Using a separate management port (Spring Boot 4)

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

  • Application port (e.g., 8080) serves your app and springdoc endpoints:

    • http://localhost:8080/v3/api-docs
    • http://localhost:8080/swagger-ui/index.html

  • Management port (e.g., 9090) serves Actuator:

    • http://localhost:9090/actuator
    • http://localhost:9090/actuator/health

Minimal application.yml:

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

With Spring Boot 3, /v3/api-docs and Swagger UI are served on the application port, while Actuator runs on the management port.
If Spring Security is enabled, explicitly permit the docs paths on the application port:

@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
  http
    .authorizeHttpRequests(auth -> auth
      .requestMatchers(
        "/v3/api-docs/**",   
        "/v3/api-docs.yaml", 
        "/swagger-ui/**",
        "/swagger-ui.html"
      ).permitAll()
      .anyRequest().authenticated()
    );
  return http.build();
}

Acknowledgements

Contributors

springdoc-openapi is relevant and updated regularly due to the valuable contributions from its contributors.

Thank you all for your support!

Additional Support

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

JenBrains logo

Frequently asked questions

Is springdoc-openapi free to use?

springdoc-openapi is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does springdoc-openapi do?

Library for OpenAPI 3 with spring-boot

What is springdoc-openapi written in?

springdoc-openapi is primarily written in Java. Its source is publicly available at https://github.com/springdoc/springdoc-openapi, and it has 3,744 GitHub stars.