Swagger详细使用介绍

Swagger 是一个用于生成、描述、调用和可视化 RESTful Web 服务的工具。它通过注解和配置自动生成 API 文档，并提供交互式的 API 测试界面。以下是 Swagger 的详细使用介绍，包含配置、注解、案例及最佳实践。

---

一、Swagger 简介

Swagger 的核心功能：

1. 自动生成 API 文档：通过注解描述 API，自动生成文档。
2. 交互式测试界面：直接在浏览器中测试 API。
3. 支持多种语言：Java、Python、Node.js 等。
4. OpenAPI 规范：遵循 OpenAPI 规范，生成的文档可与其他工具兼容。

---

二、Spring Boot 集成 Swagger

1. 添加依赖

在 pom.xml 中添加 Swagger 依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

2. 配置 Swagger

创建一个配置类启用 Swagger：

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.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)
                .apiInfo(new ApiInfoBuilder()
                        .title("API 文档")
                        .description("Spring Boot 集成 Swagger")
                        .version("1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 扫描的包路径
                .paths(PathSelectors.any())
                .build();
    }
}

3. 访问 Swagger UI

启动项目后，访问以下 URL：

http://localhost:8080/swagger-ui.html

---

三、Swagger 注解详解

Swagger 通过注解描述 API，以下是常用注解：

1. 类级别注解

注解	作用	示例
@Api	描述控制器类	@Api(tags = "用户管理")
@ApiModel	描述实体类	@ApiModel("用户实体")
@ApiOperation	描述接口方法	@ApiOperation("获取用户信息")

2. 方法级别注解

注解	作用	示例
@ApiOperation	描述接口方法	@ApiOperation("获取用户信息")
@ApiParam	描述方法参数	@ApiParam("用户ID")
@ApiResponse	描述响应状态码	@ApiResponse(code = 200, message = "成功")

3. 字段级别注解

注解	作用	示例
@ApiModelProperty	描述实体类字段	@ApiModelProperty("用户ID")

---

四、Swagger 使用案例

1. 控制器示例

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation("根据ID获取用户信息")
    public String getUserById(@PathVariable @ApiParam("用户ID") Long id) {
        return "用户ID：" + id;
    }

    @PostMapping
    @ApiOperation("创建用户")
    public String createUser(@RequestBody User user) {
        return "创建用户：" + user.getName();
    }
}

2. 实体类示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户ID")
    private Long id;

    @ApiModelProperty("用户姓名")
    private String name;

    // Getter 和 Setter
}

---

五、Swagger 高级配置

1. 分组配置

如果需要为不同的模块生成不同的文档，可以配置多个 Docket：

@Bean
public Docket userApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户管理")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.user"))
            .paths(PathSelectors.any())
            .build();
}

@Bean
public Docket orderApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("订单管理")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.order"))
            .paths(PathSelectors.any())
            .build();
}

2. 全局参数配置

如果需要为所有接口添加全局参数（如 Token），可以配置全局参数：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .globalRequestParameters(Arrays.asList(
                    new RequestParameterBuilder()
                            .name("token")
                            .description("用户Token")
                            .in(ParameterType.HEADER)
                            .required(true)
                            .build()
            ))
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.any())
            .build();
}

---

六、Swagger 最佳实践

1. 统一响应格式：
   • 使用统一的响应类（如 Result<T>），并在 Swagger 中描述。
2. 分模块管理：
   • 为不同的功能模块配置不同的 Docket。
3. 生产环境禁用：
   • 在生产环境中禁用 Swagger，避免暴露 API 信息。

   spring:
     profiles:
       active: prod
   swagger:
     enabled: false
   

---

七、总结

• Swagger 是一个强大的 API 文档工具，能够自动生成文档并提供交互式测试界面。
• 通过注解和配置，可以灵活地描述 API 和实体类。
• 结合 Spring Boot，可以快速集成 Swagger 并生成高质量的 API 文档。