Стилизация темы Swagger UI

Swagger UI предоставляет несколько способов настроить стиль интерфейса, позволяя сделать документацию более соответствующей корпоративному или продуктовому фирменному стилю.

В проекте Spring Boot вы можете создать пользовательский CSS-файл и настроить Swagger UI для его использования:

Создайте пользовательский CSS-файл, например src/main/resources/static/swagger-ui/custom.css:

Пример

/* Изменить цвет верхней панели */
.swagger-ui .topbar {
  background-color: #1e88e5;
}

/* Изменить цвета ссылок */
.swagger-ui .info a {
  color: #1e88e5;
}

/* Изменить стили кнопок */
.swagger-ui .btn.execute {
  background-color: #4576A6;
  color: white;
}

/* Изменить метки методов запроса */
.swagger-ui .opblock-get .opblock-summary-method {
  background-color: #29b6f6;
}

.swagger-ui .opblock-post .opblock-summary-method {
  background-color: #6690BB;
}

/* Изменить сворачиваемые панели */
.swagger-ui .opblock {
  border-radius: 4px;
  box-shadow: 0 1px 3px rgba(0,0,0,0.12);
}

/* Пользовательские шрифты */
.swagger-ui {
  font-family: 'Roboto', sans-serif;
}

Укажите ссылку на пользовательский CSS в конфигурации Swagger:

Пример

public SwaggerUiConfigParameters swaggerUiConfigParameters() {
    return new SwaggerUiConfigParameters()
            .withConfigUrl("/swagger-ui/custom.css");
}

Для SpringDoc OpenAPI:

Пример

# application.yml
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    config-url: /swagger-ui/custom.css

Использование плагинов тем

Для более сложной настройки темы можно использовать плагины тем Swagger UI.

Чтобы установить плагин темы (в Китае рассмотрите возможность использования других CDN или локального размещения):

Пример

<!-- Добавьте в HTML-файл -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/themes/3.x/theme-material.css">

Для проектов Express:

Пример

javascriptconst express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

const options = {
  customCssUrl: 'https://cdn.jsdelivr.net/npm/[email protected]/themes/3.x/theme-material.css'
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

К часто используемым темам относятся:

  • Material: theme-material.css
  • Monokai: theme-monokai.css
  • Muted: theme-muted.css
  • Flattop: theme-flattop.css
  • Feeling Blue: theme-feeling-blue.css

Добавление логотипа и фирменного стиля

Добавление логотипа в Spring Boot

Пример

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("Документация по интерфейсу API")
                    .version("1.0.0")
                    .description("Подробное описание интерфейса API")
                    .contact(new Contact()
                            .name("Команда разработчиков")
                            .email("[email protected]")
                            .url("https://example.com"))
                    // Добавить расширение x-logo
                    .addExtension("x-logo", Map.of(
                            "url", "/images/logo.png",
                            "backgroundColor", "#FFFFFF",
                            "altText", "Логотип компании"
                    )));
}

Добавление логотипа в Express

Пример

const swaggerOptions = {
  swaggerOptions: {
    plugins: [{
      statePlugins: {
        spec: {
          wrapSelectors: {
            info: (ori) => (...args) => {
              return {
                ...ori(...args),
                'x-logo': {
                  url: '/images/logo.png',
                  backgroundColor: '#FFFFFF',
                  altText: 'Логотип компании'
                }
              };
            }
          }
        }
      }
    }]
  }
};

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs, swaggerOptions));

Использование пользовательских шаблонов

Для более глубокой настройки можно использовать пользовательские шаблоны Swagger UI.

1. Создайте файл пользовательского шаблонаsrc/main/resources/templates/swagger-ui.html:

Пример

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Центр документации API</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css">
    <link rel="stylesheet" href="/swagger-ui/custom.css">
    <link rel="icon" type="image/png" href="/images/favicon.png" sizes="32x32">
    <style>
        .company-header {
            padding: 20px;
            background-color: #f8f8f8;
            text-align: center;
            border-bottom: 1px solid #ddd;
        }
        .логотип-компании {
            max-height: 50px;
        }
        .footer {
            text-align: center;
            padding: 20px;
            color: #666;
            font-size: 12px;
            border-top: 1px solid #ddd;
            margin-top: 20px;
        }
    </style>
</head>
<body>
    <div class="company-header">
        <img src="/images/logo.png" alt="Логотип компании" class="company-logo">
        <h1>Центр документации API</h1>
    </div>

    <div id="swagger-ui"></div>

    <div class="footer">
        <p>© 2025Название компании. Все права защищены.</p>
        <p>Если у вас есть вопросы, пожалуйста, свяжитесь с: <a href="mailto:[email protected]">api@example.com</a></p>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui-bundle.js"></script>
    <script>
        window.onload = function() {
            const ui = SwaggerUIBundle({
                url: '/v3/api-docs',
                dom_id: '#swagger-ui',
                deepLinking: true,
                пресеты: [
                    SwaggerUIBundle.presets.apis,
                    SwaggerUIBundle.SwaggerUIStandalonePreset
                ],
                layout: 'BaseLayout',
                docExpansion: 'none',
                tagsSorter: 'alpha',
                operationsSorter: 'alpha'
            });
            window.ui = ui;
        }
    </script>
</body>
</html>

2. Настройте и используйте пользовательский шаблон в проекте Spring Boot:

Пример

java@Configuration
public class SwaggerUIConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/swagger-ui/").setViewName("swagger-ui");
        registry.addRedirectViewController("/swagger-ui", "/swagger-ui/");
    }
}
Другие расширения