Spring Boot與Swagger UI美化

Spring Boot與Swagger UI的集成可以讓我們方便地測試和查看API接口，同時美化Swagger UI的界面也能提升用戶體驗。下面是一些步驟和技巧，幫助你實現這一目標。

1. 集成Swagger

首先，你需要在你的Spring Boot項目中集成Swagger。可以通過添加相關依賴來實現：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

然后，創建一個Swagger配置類：

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

確保你的控制器類上有@RestController注解，并且方法上有@ApiOperation等注解來描述API。

2. 美化Swagger UI

為了美化Swagger UI，你可以使用一些現成的庫或者自定義樣式。

使用現成的庫

有一些現成的庫可以幫助你美化Swagger UI，比如springfox-swagger-ui-themes。你可以通過以下方式添加這個庫：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui-themes</artifactId>
    <version>1.0.0</version>
</dependency>

然后在Swagger配置類中添加主題配置：

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import springfox.documentation.theme.Theme;
import springfox.documentation.theme.ThemeProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig implements ThemeProvider {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Override
    public Theme getTheme() {
        return new Theme() {
            // 自定義主題樣式
        };
    }
}

自定義樣式

你也可以通過自定義CSS樣式來美化Swagger UI。在src/main/resources目錄下創建一個static文件夾，并在其中添加一個css文件夾。然后，你可以將自定義的CSS文件放入css文件夾中。

例如，你可以創建一個名為swagger-ui.css的文件，并在其中添加一些自定義樣式：

/* 自定義Swagger UI樣式 */
body {
    font-family: Arial, sans-serif;
}

h1 {
    color: #333;
}

.swagger-ui .op-container {
    background-color: #f8f9fa;
}

.swagger-ui .info {
    background-color: #fff;
    padding: 20px;
    border-radius: 5px;
}

.swagger-ui .info h1 {
    margin-top: 0;
}

.swagger-ui .model-description {
    font-size: 14px;
    color: #6c757d;
}

最后，確保在application.properties或application.yml中配置Swagger UI的靜態資源路徑：

# application.properties
springfox.documentation.swagger.v2.path=/api-docs

或者

# application.yml
springfox:
  documentation:
    swagger:
      v2:
        path: /api-docs

這樣，當你啟動Spring Boot應用并訪問http://localhost:8080/swagger-ui.html時，你應該能看到美化后的Swagger UI界面。