Spring Boot怎样集成Swagger-UI

在现代的Web开发中，API文档是不可或缺的一部分。Swagger是一个强大的工具，可以帮助开发者生成、描述、调用和可视化RESTful风格的Web服务。Swagger-UI是Swagger的一个子项目，它提供了一个交互式的Web界面，允许开发者直接在浏览器中测试API。

本文将详细介绍如何在Spring Boot项目中集成Swagger-UI，并生成API文档。

1. 引入依赖

首先，我们需要在Spring Boot项目中引入Swagger的依赖。在pom.xml文件中添加以下依赖：

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

springfox-swagger2是Swagger的核心库，用于生成API文档。springfox-swagger-ui是Swagger-UI的库，用于提供Web界面。

2. 配置Swagger

接下来，我们需要在Spring Boot项目中配置Swagger。创建一个配置类SwaggerConfig，并添加以下代码：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
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()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot集成Swagger-UI示例")
                .description("这是一个简单的Spring Boot项目，集成了Swagger-UI。")
                .version("1.0")
                .build();
    }
}

在这个配置类中，我们使用@EnableSwagger2注解启用Swagger，并通过Docket类配置Swagger的基本信息。RequestHandlerSelectors.basePackage指定了需要生成API文档的Controller包路径。

3. 编写Controller

接下来，我们编写一个简单的Controller来测试Swagger-UI。创建一个HelloController类，并添加以下代码：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class HelloController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Swagger!";
    }
}

这个Controller定义了一个简单的GET请求，路径为/api/hello，返回一个字符串。

4. 启动项目并访问Swagger-UI

完成以上步骤后，启动Spring Boot项目。在浏览器中访问http://localhost:8080/swagger-ui.html，你将看到Swagger-UI的界面。

在Swagger-UI界面中，你可以看到我们刚刚定义的/api/hello接口。点击接口名称，可以展开详细信息，并直接在界面中测试接口。

5. 自定义Swagger-UI

Swagger-UI提供了丰富的配置选项，允许开发者自定义API文档的显示方式。以下是一些常见的自定义配置：

5.1 修改API文档标题和描述

在SwaggerConfig类中，我们可以通过ApiInfoBuilder修改API文档的标题、描述和版本信息：

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("自定义API文档标题")
            .description("这是一个自定义的API文档描述")
            .version("1.0.0")
            .build();
}

5.2 添加全局参数

如果你需要在所有API接口中添加全局参数（如认证信息），可以通过Docket的globalOperationParameters方法实现：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo())
            .globalOperationParameters(Collections.singletonList(
                    new ParameterBuilder()
                            .name("Authorization")
                            .description("认证Token")
                            .modelRef(new ModelRef("string"))
                            .parameterType("header")
                            .required(false)
                            .build()));
}

5.3 隐藏某些接口

如果你不希望某些接口出现在Swagger-UI中，可以通过@ApiIgnore注解隐藏这些接口：

import springfox.documentation.annotations.ApiIgnore;

@RestController
@RequestMapping("/api")
public class HelloController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Swagger!";
    }

    @ApiIgnore
    @GetMapping("/hidden")
    public String hidden() {
        return "This API is hidden from Swagger-UI.";
    }
}

6. 总结

通过以上步骤，我们成功地在Spring Boot项目中集成了Swagger-UI，并生成了API文档。Swagger-UI不仅可以帮助开发者快速查看和测试API，还可以通过自定义配置满足不同的需求。

在实际开发中，Swagger-UI是一个非常实用的工具，能够大大提高开发效率和API文档的可维护性。希望本文能够帮助你顺利集成Swagger-UI，并在项目中发挥其强大的功能。