How to Use springdoc OpenAPI for Spring Boot APIs

To use springdoc-openapi in a Spring Boot project, add the springdoc-openapi-starter-webmvc-ui dependency, then run your app. It automatically generates OpenAPI docs and a Swagger UI at /swagger-ui/index.html to explore your REST APIs.

Syntax

Using springdoc OpenAPI involves adding a starter dependency to your Spring Boot project and optionally configuring properties. The main parts are:

• springdoc-openapi-starter-webmvc-ui: Starter dependency that includes OpenAPI generation and Swagger UI.
• Spring Boot application: Your REST controllers are scanned automatically.
• Swagger UI endpoint: Access API docs at /swagger-ui/index.html.

plaintext

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'
}

# Optional application.properties
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui/index.html

Example

This example shows a simple Spring Boot app with a REST controller. Adding springdoc dependency auto-generates OpenAPI docs and Swagger UI.

java

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@RestController
class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, springdoc OpenAPI!";
    }
}

// build.gradle snippet
// implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0' 

Output

When running the app, visit http://localhost:8080/swagger-ui/index.html to see the interactive API docs showing the /hello endpoint.

Common Pitfalls

Common mistakes when using springdoc OpenAPI include:

• Not adding the correct starter dependency, so Swagger UI is missing.
• Using incompatible Spring Boot or springdoc versions.
• Customizing paths incorrectly in application.properties causing UI or docs to be unreachable.
• Not annotating REST controllers properly, so endpoints don't appear in docs.

Always check your dependency version matches your Spring Boot version and verify the Swagger UI URL.

plaintext

/* Wrong: Missing UI starter, only core dependency */
implementation 'org.springdoc:springdoc-openapi-webmvc-core:2.1.0'

/* Right: Include UI starter for Swagger UI */
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

Quick Reference

Feature	Description	Default Path
Dependency	springdoc-openapi-starter-webmvc-ui	N/A
API Docs URL	OpenAPI JSON docs	/v3/api-docs
Swagger UI URL	Interactive API docs UI	/swagger-ui/index.html
Customizing Paths	Use springdoc properties in application.properties	springdoc.api-docs.path, springdoc.swagger-ui.path

Key Takeaways

Add the springdoc-openapi-starter-webmvc-ui dependency to enable OpenAPI and Swagger UI.

Run your Spring Boot app and visit /swagger-ui/index.html to see interactive API docs.

Ensure your REST controllers are properly annotated to appear in the docs.

Check compatibility between springdoc and Spring Boot versions to avoid issues.

Customize paths via application.properties if needed, but use defaults for simplicity.