SpringDoc OpenAPI setup in Spring Boot

Introduction

SpringDoc OpenAPI helps you automatically create clear API documentation for your Spring Boot apps. It makes it easy for others to understand and use your APIs.

You want to show your API endpoints clearly to frontend developers.

You need to generate interactive API docs for testing your backend.

You want to keep your API documentation updated automatically.

You are building a REST API and want to follow OpenAPI standards.

You want to share your API details with external teams or clients.

Syntax

Spring Boot

1. Add SpringDoc dependency in your build file (Maven or Gradle).

For Maven:
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.1.0</version>
</dependency>

2. Run your Spring Boot app.
3. Access the API docs at: http://localhost:8080/swagger-ui/index.html

(Optional) Customize OpenAPI info by creating a @Bean of type OpenAPI.

Use the latest version of springdoc-openapi-starter-webmvc-ui for best support.

The default URL for the Swagger UI is /swagger-ui/index.html.

Examples

This is the Maven dependency to add SpringDoc OpenAPI UI support.

Spring Boot

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

This code customizes the API title, version, and description shown in the docs.

Spring Boot

@Bean
public OpenAPI customOpenAPI() {
  return new OpenAPI()
    .info(new Info().title("My API").version("1.0").description("Simple API docs"));
}

Sample Program

This Spring Boot setup adds SpringDoc OpenAPI with a custom title and a simple REST endpoint. When you run the app, you can visit /swagger-ui/index.html to see the API docs and test the /hello endpoint.

Spring Boot

package com.example.demo;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info().title("Demo API").version("1.0").description("Demo API documentation"));
    }
}

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

Important Notes

SpringDoc automatically scans your REST controllers to generate docs.

You can customize many parts of the OpenAPI spec by adding more info in the OpenAPI bean.

Make sure your app runs on port 8080 or adjust the URL accordingly.

Summary

SpringDoc OpenAPI creates live API docs for Spring Boot apps automatically.

Add the springdoc-openapi-starter-webmvc-ui dependency to enable it.

Customize docs by defining an OpenAPI bean with your API info.