天津网站建设网站智慧农业网站开发相关文档

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 {@Beanpublic 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 文档。