springdoc-openapi

The library scans Spring beans for @OpenAPIDefinition and @Info annotations to populate API metadata such as Title, version, license, security, servers, tags, and externalDocs.

For optimal performance, it is recommended to declare @OpenAPIDefinition and @SecurityScheme annotations within a Spring-managed bean.

For Spring Boot 3.x WebFlux applications requiring Swagger UI, add the springdoc-openapi-starter-webflux-ui dependency.

By default:

• Swagger UI (HTML) is available at: http://server:port/context-path/swagger-ui.html
• OpenAPI JSON is available at: http://server:port/context-path/v3/api-docs
• OpenAPI YAML is available at: http://server:port/context-path/v3/api-docs.yaml

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

To import the project into IntelliJ IDEA:

1. Use File -> Open and select the root build.gradle file.
2. Alternatively, use File -> New -> Project from Version Control and provide the URL: https://github.com/springdoc/springdoc-openapi.git.

To use project-specific formatting in Eclipse:

• Go to Help -> Install New Software.
• Add https://repo.spring.io/javaformat-eclipse-update-site/ as a new site.
• Install the "Spring Java Format" plugin.

You can build the springdoc-openapi project from the command line using Maven on JDK 1.8 or above. Run the build command from the root directory of the project.

$ ./mvn install

When reporting a bug via GitHub issues, provide the following information to speed up diagnosis:

• A detailed description of your context (the title alone is insufficient).
• The version of Spring Boot you are using.
• The specific modules and versions of springdoc-openapi being used.
• The actual result vs. the expected result (provide the OpenAPI Description in .yml or .json format).
• A Minimal, Reproducible Example (e.g., using a HelloController) that reproduces the problem.

In Spring Boot 3, when using a separate management port for Actuator, the springdoc endpoints (OpenAPI and Swagger UI) are served on the main application port. If Spring Security is enabled, you must explicitly permit access to these paths in your SecurityFilterChain configuration.

@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();
}

If you encounter Filename too long errors when cloning on Windows due to file paths exceeding 260 characters, use the core.longPaths=true git option during cloning.

git clone -c core.longPaths=true https://github.com/springdoc/springdoc-openapi

If you only need the OpenAPI JSON/YAML documentation without the Swagger UI HTML interface, add the springdoc-openapi-starter-webmvc-api dependency.

By default:

• OpenAPI JSON is available at: http://server:port/context-path/v3/api-docs
• OpenAPI YAML is available at: http://server:port/context-path/v3/api-docs.yaml

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

To ensure proper code formatting in IntelliJ IDEA, install the Spring JavaFormat plugin and import the project's code style configuration:

1. Install the Plugin:

• Download the latest IntelliJ IDEA plugin from Maven Central.
• In IntelliJ, go to IntelliJ IDEA -> Preferences -> Plugins.
• Select Install Plugin from Disk... and choose the downloaded .jar file.

2. Import Code Style:

• Go to IntelliJ IDEA -> Preferences -> Editor -> Code Style.
• Select Import Scheme -> IntelliJ IDEA code style XML.
• Select the .idea/codeStyles/codeStyleConfig.xml file from this repository.