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

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
}

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

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

Hint

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

Practice

1. What is the main purpose of adding springdoc-openapi-starter-webmvc-ui dependency in a Spring Boot project?

easy

A. To configure logging for the application

B. To enable database connectivity

C. To automatically generate live API documentation for the application

D. To add security features to the application

Solution

1. Step 1: Understand the role of springdoc-openapi-starter-webmvc-ui

   This dependency integrates SpringDoc OpenAPI with Spring Boot to generate live API docs automatically.

2. Step 2: Identify the purpose of the dependency

   It provides a user interface and backend support to display API documentation without manual setup.

3. Final Answer:

   To automatically generate live API documentation for the application -> Option C

4. Quick Check:

   SpringDoc dependency = live API docs [OK]

Hint: SpringDoc dependency creates live API docs automatically [OK]

Common Mistakes:

• Confusing it with database or security dependencies
• Thinking it configures logging
• Assuming manual doc writing is still needed

2. Which of the following is the correct way to define a basic OpenAPI bean in a Spring Boot application to customize API info?

easy

A. @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().name("API").ver("1.0")); }

B. @Bean public OpenAPI customOpenAPI() { return new OpenAPI().setTitle("API").setVersion("1.0"); }

C. @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info("API", "1.0"); }

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

Solution

1. Step 1: Recall the OpenAPI bean syntax

   The OpenAPI bean requires an Info object with title and version set via methods like title() and version().

2. Step 2: Compare options with correct method names

   Only @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("API").version("1.0")); } uses correct chaining: new OpenAPI().info(new Info().title("API").version("1.0"))

3. Final Answer:

   @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("API").version("1.0")); } -> Option D

4. Quick Check:

   OpenAPI bean uses info(new Info().title().version()) [OK]

Hint: Use Info().title() and .version() methods inside OpenAPI bean [OK]

Common Mistakes:

• Using incorrect method names like setTitle or info(String, String)
• Passing strings directly instead of Info object
• Using non-existent methods like name() or ver()

3. Given this Spring Boot configuration snippet, what will be the URL path to access the Swagger UI documentation?

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

Assuming springdoc-openapi-starter-webmvc-ui is added as dependency and no custom properties are set.

medium

A. /swagger-ui.html

B. /swagger-ui/index.html

C. /api-docs

D. /openapi-ui

Solution

1. Step 1: Recall default Swagger UI path with SpringDoc

   SpringDoc by default serves Swagger UI at /swagger-ui/index.html

2. Step 2: Eliminate other options

   /swagger-ui.html is old Swagger path, /api-docs is for JSON docs, /openapi-ui is invalid default

3. Final Answer:

   /swagger-ui/index.html -> Option B

4. Quick Check:

   Default Swagger UI path = /swagger-ui/index.html [OK]

Hint: Swagger UI default path ends with /swagger-ui/index.html [OK]

Common Mistakes:

• Using old Swagger UI path /swagger-ui.html
• Confusing JSON docs path with UI path
• Assuming custom paths without configuration

4. You added the springdoc-openapi-starter-webmvc-ui dependency but when you run your Spring Boot app, the Swagger UI page shows a 404 error. What is the most likely cause?

medium

A. You are trying to access the Swagger UI at the wrong URL

B. You did not include the springdoc-openapi-starter-webmvc-ui dependency correctly

C. You have not defined an OpenAPI bean in your configuration

D. You forgot to add the @SpringBootApplication annotation

Solution

1. Step 1: Check common reasons for 404 on Swagger UI

   Missing dependency or wrong annotation usually cause app startup errors, not 404 on UI page.

2. Step 2: Verify URL correctness

   Swagger UI default URL is /swagger-ui/index.html, accessing other URLs like /swagger-ui.html causes 404.

3. Final Answer:

   You are trying to access the Swagger UI at the wrong URL -> Option A

4. Quick Check:

   404 on Swagger UI usually means wrong URL [OK]

Hint: Check Swagger UI URL carefully if 404 occurs [OK]

Common Mistakes:

• Assuming missing OpenAPI bean causes 404
• Thinking missing @SpringBootApplication causes 404 instead of startup failure
• Ignoring URL path correctness

5. You want to customize your Spring Boot API documentation with a title "My API" and version "2.0" using SpringDoc. Which code snippet correctly achieves this and ensures the OpenAPI bean is recognized by Spring?

hard

A. @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("My API").version("2.0")); }

B. @Component public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("My API").version("2.0")); }

C. public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("My API").version("2.0")); }

D. @Configuration public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("My API").version("2.0")); }

Solution

1. Step 1: Ensure the method is a Spring bean

   To register the OpenAPI object, the method must be annotated with @Bean inside a configuration class.

2. Step 2: Check the code snippet correctness

   @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("My API").version("2.0")); } correctly uses @Bean annotation and returns new OpenAPI().info(new Info().title("My API").version("2.0"))

3. Final Answer:

   @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info().title("My API").version("2.0")); } -> Option A

4. Quick Check:

   Use @Bean annotation to register OpenAPI bean [OK]

Hint: Use @Bean annotation on method returning OpenAPI [OK]

Common Mistakes:

• Omitting @Bean annotation so Spring ignores the method
• Using @Component or @Configuration on method instead of class
• Not returning an OpenAPI object with info set