YouTip
Swagger Ui Modify
Swagger UI provides multiple ways to customize the interface style to make the documentation more aligned with enterprise or product brand image.
In a Spring Boot project, you can create a custom CSS file and configure Swagger UI to use it:
Create a custom CSS file, for example src/main/resources/static/swagger-ui/custom.css:
## Example
/* Modify top bar color */
.swagger-ui.topbar{
background-color:#1e88e5;
}
/* Modify link color */
.swagger-ui.info a {
color:#1e88e5;
}
/* Modify button style */
.swagger-ui.btn.execute{
background-color:#43a047;
color:white;
}
/* Modify request method tags */
.swagger-ui.opblock-get.opblock-summary-method{
background-color:#29b6f6;
}
.swagger-ui.opblock-post.opblock-summary-method{
background-color:#66bb6a;
}
/* Modify collapsible panels */
.swagger-ui.opblock{
border-radius:4px;
box-shadow:0 1px 3px rgba(0,0,0,0.12);
}
/* Custom font */
.swagger-ui{
font-family:'Roboto',sans-serif;
}
Reference the custom CSS in Swagger configuration:
## Example
public SwaggerUiConfigParameters swaggerUiConfigParameters(){
return new SwaggerUiConfigParameters()
.withConfigUrl("/swagger-ui/custom.css");
}
For SpringDoc OpenAPI:
## Example
# application.yml
springdoc:
swagger-ui:
path:/swagger-ui.html
config-url:/swagger-ui/custom.css
### Using Theme Plugins
For more complex theme customization, you can use Swagger UI theme plugins.
Install theme plugins (consider other CDNs or host locally for domestic use):
## Example
For Express projects:
## Example
javascriptconst express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const options ={
customCssUrl:'https://cdn.jsdelivr.net/npm/swagger-ui-themes@3.0.0/themes/3.x/theme-material.css'
};
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
Common themes include:
* Material: `theme-material.css`
* Monokai: `theme-monokai.css`
* Muted: `theme-muted.css`
* Flattop: `theme-flattop.css`
* Feeling Blue: `theme-feeling-blue.css`
### Adding Logo and Brand Identity
#### Adding Logo in Spring Boot
## Example
@Bean
public OpenAPI customOpenAPI(){
return new OpenAPI()
.info(new Info()
.title("API Documentation")
.version("1.0.0")
.description("API Detailed Description")
.contact(new Contact()
.name("Development Team")
.email("team@example.com")
.url("https://example.com"))
// Add x-logo extension
.addExtension("x-logo", Map.of(
"url", "/images/logo.png",
"backgroundColor", "#FFFFFF",
"altText", "Company Logo"
)));
}
#### Adding Logo in Express
## Example
const swaggerOptions={
swaggerOptions:{
plugins:[{
statePlugins:{
spec:{
wrapSelectors:{
info:(ori)=>(...args)=>{
return{
...ori(...args),
'x-logo':{
url:'/images/logo.png',
backgroundColor:'#FFFFFF',
altText:'Company Logo'
}
};
}
}
}
}]
}
};
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs, swaggerOptions));
### Using Custom Templates
**For deeper customization, you can use custom Swagger UI templates.**
**1. Create custom template file `src/main/resources/templates/swagger-ui.html`:**
## Example
API Documentation Center
.company-header {
padding: 20px;
background-color: #f8f8f8;
text-align: center;
border-bottom: 1px solid #ddd;
}
.company-logo {
max-height: 50px;
}
.footer{
text-align: center;
padding: 20px;
color: #666;
font-size: 12px;
border-top: 1px solid #ddd;
margin-top: 20px;
}
window.onload=function(){
const ui = SwaggerUIBundle({
url:'/v3/api-docs',
dom_id:'#swagger-ui',
deepLinking:true,
presets:[
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout:'BaseLayout',
docExpansion:'none',
tagsSorter:'alpha',
operationsSorter:'alpha'
});
window.ui= ui;
}
**2. Configure to use custom template in Spring Boot project:**
## Example
java@Configuration
public class SwaggerUIConfig implements WebMvcConfigurer {
@Override
public void addViewControllers(ViewControllerRegistry registry){
registry.add