swagger 注解

### Swagger注解的使用方法与示例 Swagger注解是用于描述API接口和参数的重要工具，它能够帮助开发者自动生成API文档[^1]。以下是关于如何使用Swagger注解以及一些常见的示例代码。 #### 1. 引入依赖 在使用Swagger注解之前，需要确保项目中已经引入了相关的依赖。例如，在Maven项目中可以添加以下依赖： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` #### 2. 配置Swagger 在Spring Boot项目中，可以通过配置类启用Swagger功能。以下是一个简单的配置示例： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } } ``` #### 3. 使用常见注解 Swagger提供了多种注解来描述API接口及其参数。以下是一些常用的注解及其功能： - **@Api**：用于类上，描述该控制器的功能或模块名称。 ```java @Api(tags = "用户管理模块") ``` - **@ApiOperation**：用于方法上，描述接口的具体操作及说明。 ```java @ApiOperation(value = "获取用户信息", notes = "根据用户ID查询用户详细信息") ``` - **@ApiParam**：用于方法参数上，描述参数的作用及约束条件。 ```java @GetMapping("/user/{id}") public ResponseEntity<User> getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) { // 方法实现 } ``` - **@ApiResponse**：用于描述接口可能返回的响应结果。 ```java @ApiResponse(code = 404, message = "未找到指定资源") ``` - **@ApiModel** 和 **@ApiModelProperty**：用于描述复杂的对象模型。 ```java @ApiModel(description = "用户实体类") public class User { @ApiModelProperty(value = "用户ID", example = "1") private Long id; @ApiModelProperty(value = "用户名", example = "张三") private String name; } ``` #### 4. 示例代码 以下是一个完整的示例代码，展示了如何使用Swagger注解描述一个简单的API接口： ```java @RestController @RequestMapping("/api/user") @Api(tags = "用户管理模块", description = "提供用户相关操作的API接口") public class UserController { @ApiOperation(value = "创建用户", notes = "根据用户信息创建新用户") @PostMapping("/create") public ResponseEntity<String> createUser(@RequestBody @ApiParam(value = "用户信息") User user) { // 创建用户的逻辑 return ResponseEntity.ok("用户创建成功"); } @ApiOperation(value = "获取用户信息", notes = "根据用户ID查询用户详细信息") @ApiResponses({ @ApiResponse(code = 200, message = "成功返回用户信息"), @ApiResponse(code = 404, message = "未找到指定用户") }) @GetMapping("/get/{id}") public ResponseEntity<User> getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) { // 查询用户的逻辑 return ResponseEntity.ok(new User()); } } ``` #### 5. 注意事项 在使用Swagger注解时需要注意以下几点： - 确保注解的描述清晰、简洁且符合实际需求[^2]。 - 避免超出Swagger-UI页面可展示的字符限制（通常为120个字符以内）[^3]。 - 对于复杂的数据结构，建议使用`@ApiModel`和`@ApiModelProperty`进行详细描述。 ---