SpringDoc OpenAPI setup in Spring Boot - Mini Project: Build & Apply

SpringDoc OpenAPI setup

📖 Scenario: You are building a simple Spring Boot REST API for a bookstore. You want to add automatic API documentation using SpringDoc OpenAPI so that users can easily see and test your API endpoints.

🎯 Goal: Set up SpringDoc OpenAPI in your Spring Boot project to generate interactive API documentation accessible via a web browser.

📋 What You'll Learn

Add the SpringDoc OpenAPI dependency to the project

Create a configuration bean for OpenAPI info

Annotate the main application class with @OpenAPIDefinition

Verify the OpenAPI UI is accessible at /swagger-ui.html

💡 Why This Matters

🌍 Real World

API documentation helps developers understand and test your REST APIs easily without extra tools.

💼 Career

Many companies use OpenAPI and SpringDoc to maintain clear API docs, which is a valuable skill for backend developers.

1

Add SpringDoc OpenAPI dependency

Add the SpringDoc OpenAPI starter dependency to your build.gradle file with this exact line: implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

Spring Boot

// Add the SpringDoc OpenAPI dependency line below
// Your code here

Need a hint?

Look for the dependencies block in build.gradle and add the exact dependency line inside it.

2

Create OpenAPI configuration bean

In a new Java class called OpenApiConfig, create a Spring @Bean method named customOpenAPI that returns an OpenAPI object with the title set to "Bookstore API" and version "1.0". Use new OpenAPI().info(new Info().title("Bookstore API").version("1.0")).

Spring Boot

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

package com.example.bookstore;

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;

@Configuration
public class OpenApiConfig {
    // Create a @Bean method named customOpenAPI returning OpenAPI with title 'Bookstore API' and version '1.0'
    // Your code here
}

Need a hint?

Define a method annotated with @Bean that returns the OpenAPI object with the specified title and version.

3

Annotate main application with @OpenAPIDefinition

In your main Spring Boot application class named BookstoreApplication, add the import for io.swagger.v3.oas.annotations.OpenAPIDefinition and annotate the class with @OpenAPIDefinition.

Spring Boot

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

package com.example.bookstore;

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;

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

package com.example.bookstore;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
// Add import for OpenAPIDefinition here

@SpringBootApplication
// Add @OpenAPIDefinition annotation here
public class BookstoreApplication {
    public static void main(String[] args) {
        SpringApplication.run(BookstoreApplication.class, args);
    }
}

Need a hint?

Import OpenAPIDefinition and add it as an annotation above the main application class.

4

Verify OpenAPI UI accessibility

Ensure your Spring Boot application is running and open a web browser to http://localhost:8080/swagger-ui.html to see the interactive API documentation generated by SpringDoc OpenAPI.

Spring Boot

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

package com.example.bookstore;

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;

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

package com.example.bookstore;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;

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

// Run the application and open http://localhost:8080/swagger-ui.html in your browser
// Your code here

Need a hint?

Start your Spring Boot app and visit the URL to see the API docs UI.