当前位置：首页 > news >正文

Swagger详细使用介绍

news 来源：原创 2025/6/15 12:25:06

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

一、Swagger 简介

Swagger 的核心功能：

自动生成 API 文档：通过注解描述 API，自动生成文档。
交互式测试界面：直接在浏览器中测试 API。
支持多种语言：Java、Python、Node.js 等。
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 最佳实践

统一响应格式：
- 使用统一的响应类（如 Result<T>），并在 Swagger 中描述。
分模块管理：
- 为不同的功能模块配置不同的 Docket。
生产环境禁用：
- 在生产环境中禁用 Swagger，避免暴露 API 信息。
```
spring:
  profiles:
    active: prod
swagger:
  enabled: false
```