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-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");
}
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
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">
<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));
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", 会社ロゴ
)));
}
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));
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>
<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/");
}
}
public class SwaggerUIConfig implements WebMvcConfigurer {
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController("/swagger-ui/").setViewName("swagger-ui");
registry.addRedirectViewController("/swagger-ui", "/swagger-ui/");
}
}