Swagger UI integration in Spring Boot

Introduction

Swagger UI helps you see and test your API in a simple web page. It makes understanding and using your API easier.

You want to show your API to other developers clearly.

You want to test your API endpoints without writing extra code.

You want automatic API documentation that updates with your code.

You want to share your API details with your team or clients.

You want to find and fix API issues faster by trying calls directly.

Syntax

Spring Boot

1. Add dependency in build file (pom.xml 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. Open browser at http://localhost:8080/swagger-ui/index.html

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

No extra configuration is needed for basic setup.

Examples

This is the Maven dependency to add Swagger UI support.

Spring Boot

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

A simple API controller to test Swagger UI.

Spring Boot

@RestController
@RequestMapping("/api")
public class HelloController {

  @GetMapping("/hello")
  public String sayHello() {
    return "Hello, Swagger!";
  }
}

Access Swagger UI in your browser to see and test the API.

Spring Boot

# Run the Spring Boot app and visit:
http://localhost:8080/swagger-ui/index.html

Sample Program

This Spring Boot app has one API endpoint /api/hello. After adding the Swagger UI dependency, you can open http://localhost:8080/swagger-ui/index.html to see this endpoint documented and test it interactively.

Spring Boot

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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

@RestController
@RequestMapping("/api")
class HelloController {
  @GetMapping("/hello")
  public String sayHello() {
    return "Hello, Swagger!";
  }
}

Important Notes

Swagger UI automatically reads your Spring Boot API endpoints and shows them.

You can customize Swagger UI with properties if needed, but basic use requires no setup.

Make sure your API controllers use standard Spring annotations like @RestController and @GetMapping.

Summary

Swagger UI shows your API in a friendly web page for easy testing and documentation.

Add the springdoc-openapi starter dependency to your Spring Boot project to enable it.

Visit /swagger-ui/index.html in your browser to see your API live.

Practice

1. What is the main purpose of integrating Swagger UI in a Spring Boot project?

easy

A. To improve database performance

B. To generate frontend UI components

C. To handle user authentication automatically

D. To provide a web page that documents and allows testing of your API

Solution

1. Step 1: Understand Swagger UI's role

   Swagger UI creates a friendly web interface to view and test API endpoints.

2. Step 2: Compare options

   Only To provide a web page that documents and allows testing of your API describes this purpose; others relate to unrelated features.

3. Final Answer:

   To provide a web page that documents and allows testing of your API -> Option D

4. Quick Check:

   Swagger UI = API documentation and testing [OK]

Hint: Swagger UI = API docs + testing page [OK]

Common Mistakes:

• Confusing Swagger UI with database tools
• Thinking Swagger handles authentication
• Assuming Swagger generates frontend code

2. Which dependency should you add to a Spring Boot project to enable Swagger UI with springdoc-openapi?

easy

A. springdoc-openapi-starter-webmvc-ui

B. spring-boot-starter-data-jpa

C. spring-boot-starter-web

D. spring-security-oauth2-client

Solution

1. Step 1: Identify the correct starter for Swagger UI

   The springdoc-openapi-starter-webmvc-ui dependency enables Swagger UI integration in Spring Boot.

2. Step 2: Eliminate unrelated dependencies

   Other options relate to web server, database, or security, not Swagger UI.

3. Final Answer:

   springdoc-openapi-starter-webmvc-ui -> Option A

4. Quick Check:

   Swagger UI dependency = springdoc-openapi-starter-webmvc-ui [OK]

Hint: Use springdoc-openapi-starter-webmvc-ui for Swagger UI [OK]

Common Mistakes:

• Adding only spring-boot-starter-web without Swagger
• Using database or security starters by mistake
• Forgetting to add any Swagger-related dependency

3. Given a Spring Boot app with springdoc-openapi-starter-webmvc-ui added, what URL should you visit to see the Swagger UI page?

medium

A. /openapi-ui/index.html

B. /api-docs/swagger-ui.html

C. /swagger-ui/index.html

D. /swagger-ui.html

Solution

1. Step 1: Recall the default Swagger UI path

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

2. Step 2: Check other options

   Other URLs are incorrect or outdated paths for Swagger UI.

3. Final Answer:

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

4. Quick Check:

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

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

Common Mistakes:

• Using /swagger-ui.html which is deprecated
• Confusing API docs JSON URL with UI URL
• Trying /openapi-ui which is invalid

4. You added springdoc-openapi-starter-webmvc-ui but visiting /swagger-ui/index.html shows 404 error. What is the most likely cause?

medium

A. You did not enable @EnableSwagger2 annotation

B. You need to restart the Spring Boot app after adding dependency

C. You forgot to add spring-boot-starter-web dependency

D. Swagger UI is only available in Spring Boot 3.x and above

Solution

1. Step 1: Check common setup issues

   After adding a new dependency, the app must be restarted to load it properly.

2. Step 2: Evaluate other options

   @EnableSwagger2 is not needed with springdoc-openapi; spring-boot-starter-web is usually present; Swagger UI works on Spring Boot 2.x too.

3. Final Answer:

   You need to restart the Spring Boot app after adding dependency -> Option B

4. Quick Check:

   Restart app after adding Swagger dependency [OK]

Hint: Restart app after adding dependencies to avoid 404 [OK]

Common Mistakes:

• Thinking @EnableSwagger2 is required with springdoc-openapi
• Missing spring-boot-starter-web (usually present)
• Assuming Swagger UI needs Spring Boot 3 only

5. You want to customize the Swagger UI page title and description in your Spring Boot app using springdoc-openapi. Which approach is correct?

hard

A. Add a bean of type OpenAPI and set info title and description

B. Edit the swagger-ui.html file directly in resources

C. Use @EnableSwagger2 annotation with title parameter

D. Set springdoc.swagger-ui.title property in application.properties

Solution

1. Step 1: Understand customization with springdoc-openapi

   Customizing title and description is done by defining an OpenAPI bean with Info details.

2. Step 2: Eliminate incorrect methods

   Editing swagger-ui.html is not recommended; @EnableSwagger2 is for older Swagger versions; springdoc.swagger-ui.title property does not exist.

3. Final Answer:

   Add a bean of type OpenAPI and set info title and description -> Option A

4. Quick Check:

   Customize Swagger UI via OpenAPI bean [OK]

Hint: Customize Swagger UI by defining OpenAPI bean [OK]

Common Mistakes:

• Trying to edit swagger-ui.html manually
• Using outdated @EnableSwagger2 annotation
• Expecting a springdoc property for title customization