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;
}

Swagger 設定でカスタム CSS を参照します:

サンプル

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/swagger-ui-themes@3.0.0/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/swagger-ui-themes@3.0.0/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("team@example.com")
                            .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/swagger-ui-dist@4.5.0/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;
        }
        .company-logo {
            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:api@example.com">api@example.com</a></p>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4.5.0/swagger-ui-bundle.js"></script>
    <script>
        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;
        }
    </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/");
    }
}
その他の拡張