Swagger UI integration in Spring Boot - Performance & Optimization

Performance: Swagger UI integration

MEDIUM IMPACT

This affects the initial page load speed and bundle size of the API documentation interface.

Serving API documentation with Swagger UI in a Spring Boot app

Spring Boot

Configure HTTP caching headers for Swagger UI static resources and enable lazy loading of Swagger UI only when needed

Reduces repeated downloads and delays loading Swagger UI until user requests it.

📈 Performance Gainsaves ~200kb on initial load, reduces blocking time to under 50ms

Serving API documentation with Swagger UI in a Spring Boot app

Spring Boot

springdoc-openapi-ui dependency included without any resource caching or lazy loading configuration

Swagger UI assets load fully on every page visit, increasing bundle size and blocking rendering.

📉 Performance Costadds ~300kb to initial bundle, blocks rendering for 100-200ms on slow networks

Performance Comparison

Pattern	DOM Operations	Reflows	Paint Cost	Verdict
Load full Swagger UI on every page load	High (many nodes for UI)	Multiple reflows due to script execution	High paint cost for UI elements	[X] Bad
Lazy load Swagger UI on demand with caching	Low (only when needed)	Single reflow after load	Lower paint cost	[OK] Good

Rendering Pipeline

Swagger UI integration loads additional CSS and JavaScript files which the browser must parse and execute before rendering the API docs page.

→Network

→Style Calculation

→Layout

→Paint

→Composite

⚠️ BottleneckNetwork and JavaScript execution delay the Style Calculation and Layout stages.

Core Web Vital Affected

LCP

This affects the initial page load speed and bundle size of the API documentation interface.

Optimization Tips

1Serve Swagger UI assets with proper caching headers to avoid repeated downloads.

2Lazy load Swagger UI scripts only when the user requests API documentation.

3Minimize Swagger UI bundle size by excluding unused features or customizing the build.

Performance Quiz - 3 Questions

What is the main performance impact of integrating Swagger UI in a Spring Boot app?

A Increased initial page load time due to large JS and CSS assets

B Increased server CPU usage during API calls

C Slower database queries

D Higher memory usage on client devices

DevTools: Network and Performance panels

How to check: Open DevTools, go to Network tab, reload page and check Swagger UI asset sizes and load times. Then use Performance tab to record page load and see scripting and rendering delays.

What to look for: Look for large Swagger UI JS/CSS files blocking main thread and delaying LCP. Check if caching headers are present to avoid repeated downloads.

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