Embedding Swagger UI within Spring Boot applications has become a popular way of documenting RESTful APIs. But when you’re working regularly with APIs, staring at a white-themed interface can get tiring quickly, especially during long coding sessions or late-night debugging marathons. A dark mode Swagger UI can significantly reduce eye strain and make your API documentation visually appealing for users who prefer darker interfaces.
Let’s first make sure we’re set up correctly before diving straight into applying custom CSS to Swagger UI.
Setting up Swagger UI in Spring Boot Application
To integrate Swagger UI within your Spring Boot app, start by adding the necessary dependencies into your project’s pom.xml file if you’re using Maven:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.7.0</version>
</dependency>
This dependency will automatically set up your Swagger documentation at a default URL (/swagger-ui.html).
Next, you’ll need to configure your Swagger UI properly in your Spring Boot application. Create or use your existing Swagger configuration class (typically known as SwaggerConfig.java). It should look something similar to this:
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info().title("API Documentation")
.version("1.0")
.description("My App API"));
}
}
Ensure your application properly scans the necessary packages for RestControllers so Swagger can pick up all endpoints automatically.
With Swagger now set up, let’s get ready to style it with custom CSS. Since Swagger UI supports custom styling through CSS, you just need your custom CSS file in the right directory. Typically, these CSS files reside within your resources/static folder. Your file structure might look something like this:
src/
main/
resources/
static/
swagger-ui/
swagger-custom.css
Implementing Dark Mode for Swagger UI
Swagger UI is relatively straightforward when it comes to customization. With some clever use of CSS targeting, you can give it a nice and comfortable dark mode look.
Start by creating your custom CSS file (swagger-custom.css) inside the path we defined earlier. Here’s a simplified example of dark mode styling to get you started:
body {
background-color: #121212;
color: #e0e0e0;
}
.topbar {
background-color: #2c2c2c;
border-color: #444;
}
.swagger-ui .opblock {
background: #242424;
border-color: #3a3a3a;
}
.swagger-ui .opblock .opblock-summary {
color: #ccc;
}
.swagger-ui .btn {
background-color: #333;
color: #ddd;
}
.swagger-ui .btn:hover {
background-color: #555;
}
.swagger-ui .title {
color: #bbb;
}
This snippet provides a basic yet comfortable dark aesthetic. Feel free to expand and tailor this to your liking or organization’s guidelines.
Next, you’ll link your custom CSS directly into Swagger UI using your application’s configuration. Without explicit linking, Swagger won’t be aware of the existence of your customized CSS.
To inform Swagger UI about your custom CSS, modify your application.properties (or application.yml) file:
springdoc.swagger-ui.custom-css-url=/swagger-ui/swagger-custom.css
Alternatively, you can set custom CSS using Java code within your existing Swagger configuration class:
@Configuration
public class SwaggerConfig {
@Bean
public SwaggerUiConfigParameters swaggerUiConfigParameters() {
SwaggerUiConfigParameters params = new SwaggerUiConfigParameters();
params.setConfigUrl("/swagger-ui/swagger-custom.css");
return params;
}
}
If you’d rather keep everything organized in Java configuration, the Java-based solution above is straightforward.
Troubleshooting Common Issues
After integrating custom CSS and eagerly restarting your Spring Boot application, you may run into unexpected behavior. A common issue is the UI not loading correctly, with errors suggesting it’s unable to find or load resources.
Suppose your browser console shows errors about Swagger UI unable to reach a resource like “https://petstore.swagger.io/v2/swagger.json”. This usually suggests a configuration issue rather than a CSS problem.
When Swagger can’t locate your API documentation file, it falls back to the default petstore reference URL. Don’t panic—typically, this indicates your configuration doesn’t specify your OpenAPI documentation correctly.
Verify your Swagger configuration using Spring’s @Configuration annotation properly. Ensure the annotated beans are correctly picked up by Spring and that mapped API endpoints exist:
- Check if package scanning is properly set up in your Spring Boot application (Spring Boot guide).
- Ensure required dependencies exist in your build configuration.
- Verify your resource folder path and naming conventions.
Your Swagger UI configuration might need the exact path for your API documentation. For instance, in your application.properties, ensure something like this is present:
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.url=/v3/api-docs
This explicit path setup tells Swagger exactly where to locate the JSON documentation file, resolving redirection to the petstore URL.
Also, for CSS issues:
- Ensure correct CSS file path: using browser inspector, verify that the file swagger-custom.css is loaded correctly from the expected static resource endpoint.
- If it isn’t loading, verify spelling carefully, case-sensitivity, and your static resource mapping configuration in Spring Boot.
For detailed troubleshooting steps or specific errors, you might want to check Stack Overflow’s Swagger UI tag, as someone else likely faced the same issue.
Wrapping Up Your Swagger UI Dark Mode Implementation
Making Swagger UI easy on the eyes with a pleasant dark mode requires only minimal setup in your Spring Boot App:
- Add proper dependencies to your Spring Boot project’s build file.
- Create your customized dark mode CSS file in the static resources directory.
- Properly link this CSS file to Swagger UI using either application properties or Java configuration.
- Troubleshoot possible errors like incorrect Swagger URLs or misconfigured beans.
Once everything is set up properly, you’ll soon see the satisfying sight of a stylish dark-themed Swagger UI, reducing eye fatigue during those long coding sprints. If you’re interested in more custom JavaScript solutions in applications like this, check out these JavaScript articles.
Have you already customized your Swagger UI? Share your experience or custom dark themes with others in the comments below!
0 Comments