Swagger是一个流行的API文档和交互式测试工具，它可以帮助开发者轻松地创建、测试和维护API文档。本文将手把手教你如何搭建Swagger接口文档，并提供实例解析。

一、环境准备

在开始之前，请确保你的开发环境中已经安装了以下工具：

• Java开发环境（JDK 1.8+）
• Maven（用于依赖管理）
• 一个IDE（如IntelliJ IDEA或Eclipse）

二、创建项目

1. 使用Maven创建一个新的Spring Boot项目。
2. 在pom.xml文件中添加以下依赖：

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- 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>
</dependencies>

1. 在src/main/java目录下创建一个SwaggerConfig类，用于配置Swagger：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

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

1. 在src/main/resources目录下创建一个application.properties文件，添加以下配置：

springfox.documentation.swagger2.enabled=true

三、编写API接口

1. 在com.example包下创建一个HelloController类，用于编写API接口：

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

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

四、启动项目

1. 运行HelloController类所在的Spring Boot应用。
2. 打开浏览器，访问http://localhost:8080/swagger-ui.html。

五、实例解析

在Swagger UI中，你可以看到以下信息：

• API基本信息：包括标题、版本、描述等。
• 接口列表：列出所有API接口及其路径、HTTP方法、参数等信息。
• 接口测试：可以直接在Swagger UI中对API接口进行测试。

六、总结

通过以上步骤，你已经成功搭建了一个Swagger接口文档。在实际开发中，你可以根据需要添加更多的API接口和配置项。Swagger可以帮助你快速生成、测试和维护API文档，提高开发效率。