Swagger UI integration in Spring Boot - Step-by-Step Execution

Concept Flow - Swagger UI integration

Add Swagger dependencies

↓

Configure Swagger bean

↓

Start Spring Boot app

↓

Swagger UI available at /swagger-ui/index.html

↓

Access API docs interactively

This flow shows adding Swagger to a Spring Boot app, configuring it, running the app, and accessing the interactive API docs.

Execution Sample

Spring Boot

springdoc:
  api-docs:
    path: /v3/api-docs

@Bean
public OpenAPI customOpenAPI() {
  return new OpenAPI();
}

This code configures Springdoc OpenAPI to generate API docs and expose Swagger UI.

Execution Table

Step	Action	Result	Effect
1	Add springdoc-openapi-ui dependency	Dependency added	Enables Swagger UI support
2	Create OpenAPI bean in config	Bean registered	Customizes API docs generation
3	Run Spring Boot app	App starts	API docs generated at /v3/api-docs
4	Open browser at /swagger-ui/index.html	Swagger UI loads	Interactive API docs visible
5	Use Swagger UI to test endpoints	Requests sent	API responses shown in UI
6	Stop app	App stops	Swagger UI no longer available

💡 App stops or user closes Swagger UI, ending interaction

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
springdoc-openapi-ui dependency	Not present	Added	Added	Added	Added	Added
OpenAPI bean	Not defined	Not defined	Defined	Defined	Defined	Defined
Spring Boot app state	Stopped	Stopped	Stopped	Running	Running	Stopped
Swagger UI availability	No	No	No	Yes	Yes	No

Key Moments - 3 Insights

Why do we need to add the springdoc-openapi-ui dependency first?

Because without the dependency, the Swagger UI components and API doc generation are not available, as shown in execution_table step 1.

What happens if we don't create the OpenAPI bean?

Swagger UI still works with default settings, but you cannot customize API docs. This is shown in execution_table step 2 where the bean is registered to customize.

Why can't we see Swagger UI before running the app?

Swagger UI is served by the running Spring Boot app, so until the app is running (step 3), the UI is not accessible (step 4).

Visual Quiz - 3 Questions

Look at the execution_table, at which step does the Swagger UI become accessible?

A Step 3

B Step 4

C Step 2

D Step 1

💡 Hint

Check the 'Swagger UI availability' variable in variable_tracker after each step.

According to variable_tracker, what is the state of the Spring Boot app after Step 2?

A Starting

B Running

C Stopped

D Crashed

💡 Hint

Look at the 'Spring Boot app state' row in variable_tracker after Step 2.

If we remove the OpenAPI bean configuration, what changes in the execution flow?

A API docs will use default settings

B App will fail to start

C Swagger UI will not load at all

D Swagger UI URL changes

💡 Hint

Refer to key_moments about the OpenAPI bean effect on customization.

Concept Snapshot

Swagger UI integration in Spring Boot:
1. Add springdoc-openapi-ui dependency.
2. Optionally create OpenAPI bean to customize.
3. Run app to generate API docs.
4. Access Swagger UI at /swagger-ui/index.html.
5. Use UI to explore and test APIs interactively.

Full Transcript

To integrate Swagger UI in a Spring Boot application, first add the springdoc-openapi-ui dependency to your project. Then, optionally create an OpenAPI bean to customize the API documentation. When you run the Spring Boot app, it generates API docs accessible at /v3/api-docs. You can open the Swagger UI in a browser at /swagger-ui/index.html to see interactive API documentation and test endpoints. The Swagger UI is only available while the app is running. This process helps developers and users understand and try the API easily.

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