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界面。