Spring Boot 整合 Spring Fox 生成 Swagger 文档

前言

随着前后端分离的开发模式越来越流行，API 的设计与文档变得尤为重要。Swagger 是一个流行的 API 文档生成工具，它可以通过注解将 API 接口自动转化为文档，并且提供了友好的 UI 来展示这些文档。在 Spring Boot 项目中，我们可以使用 Spring Fox 来集成 Swagger，实现自动生成 API 文档。本篇博客将介绍如何使用 Spring Fox 来整合 Swagger，并且美化文档界面。

步骤一：添加依赖

首先，在项目的 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

步骤二：配置 Swagger

在 Spring Boot 项目中，我们可以通过配置类来配置 Swagger。

首先，创建一个配置类 SwaggerConfig，添加 @Configuration 注解使其成为一个配置类：

@Configuration
public class SwaggerConfig {
    
}

在配置类中，我们需要配置 Docket，它是 Spring Fox 的主要配置类。在 SwaggerConfig 类中添加以下方法：

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

上述代码中，RequestHandlerSelectors.basePackage 指定了需要生成文档的 API 所在的包路径，你可以根据实际情况进行调整。

步骤三：启用 Swagger

在启动类中添加 @EnableSwagger2 注解来启用 Swagger：

@SpringBootApplication
@EnableSwagger2
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

步骤四：生成文档

启动应用程序并访问 http://localhost:8080/swagger-ui/index.html，你将看到自动生成的 Swagger 文档界面。

步骤五：美化界面

默认生成的 Swagger 文档界面并不美观，但是你可以通过添加自定义 CSS 文件来美化界面。下面是一个简单的方法来实现界面美化：

在项目的 resources 目录下创建 static 目录。
在 static 目录下创建一个名为 swagger.css 的 CSS 文件，用来定义界面样式。
在 SwaggerConfig 类中添加一个 WebMvcConfigurer Bean，将 CSS 文件添加到静态资源处理器中：

@Bean
public WebMvcConfigurer webMvcConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/swagger-ui/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
                    .resourceChain(false)
                    .addTransformer((request, response, chain) -> {
                        response.setHeader("Cache-Control", "no-store");
                        chain.transform(request, response);
                    });
            registry.addResourceHandler("/custom/**")
                    .addResourceLocations("classpath:/static/");
        }
    };
}

启动应用程序并访问 http://localhost:8080/custom/swagger-ui/index.html，你将看到美化后的 Swagger 文档界面。

总结

使用 Spring Fox 可以很方便地生成 Swagger 文档，并且通过配置自定义样式可以美化文档界面。在实际开发中，合理设计 API 并生成详细的文档是非常重要的，它可以提高团队协作效率，减少沟通成本。希望本篇博客对大家能有所帮助。

本文来自极简博客，作者：落日余晖，转载请注明原文链接：Spring Boot 整合 Spring Fox 生成 Swagger 文档