Swagger接口文档 —— 手把手教学，全方位超详细小白能看懂，百分百能用Java版

Swagger 是一个用于描述、消费和可视化 RESTful Web 服务的工具。它通过一个简单的注解和配置方式，帮助我们快速生成接口文档。本文将手把手教你如何使用 Swagger 生成 Java 项目中的接口文档，即使是小白也能看懂。

什么是 Swagger？

Swagger 是一种开放的API描述规范，允许我们使用 YAML 或 JSON 来描述 RESTful APIs 的结构。通过使用 Swagger，我可以自动生成文档，甚至是 API 的客户端代码，从而提高开发效率。

环境准备

首先，确保你的 Java 项目中已经添加了 Swagger 的依赖。假设你使用 Maven 来管理项目的依赖，以下是添加 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

接下来，你需要在 Spring Boot 项目中进行基本的配置。创建一个 Swagger 配置类，例如 SwaggerConfig.java：

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;
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.controller")) // 设置API扫描的包
                .paths(PathSelectors.any())
                .build();
    }
}

创建一个示例接口

我们来创建一个简单的 RESTful API 接口，并使用 Swagger 的注解来说明接口文档。以下是一个简单的控制器示例：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@Api(tags = "用户管理接口")
public class UserController {

    @GetMapping("/user")
    @ApiOperation(value = "获取用户信息", notes = "根据用户名获取对应的用户信息")
    public String getUser(@RequestParam String username) {
        return "用户信息: " + username;
    }
}

运行项目

完成以上步骤后，启动你的 Spring Boot 项目。Swagger 默认生成的接口文档可以通过访问 http://localhost:8080/v2/api-docs 获取，而 Swagger UI 可以通过 http://localhost:8080/swagger-ui.html 访问。

Swagger UI 的使用

在 Swagger UI 页面上，你可以看到所有暴露的API信息，包括请求的方法、路径、参数及返回值。用户可以直接在页面上测试 API，查看返回结果。

注意事项

1. 依赖版本：确保依赖包的版本与 Spring Boot 版本相匹配。
2. 配置路径：根据你的项目结构，注意调整 basePackage 的值，确保 Swagger 能发现你的控制器类。
3. 注解使用：使用 @Api 和 @ApiOperation 注解来对类和方法进行注释，有助于生成清晰的文档。

总结

通过上面的步骤，大家应该可以简单地使用 Swagger 来生成 Java 项目的接口文档了。这个过程不仅提高了文档生成的效率，同时也方便了团队成员之间的沟通和协作。希望您在使用 Swagger 的过程中顺利，如有问题随时交流！