Swagger2的常用注解

Swagger2 是一个用于生成、描述和调用 RESTful 接口的工具，通过注解可以增强 API 文档的可读性和交互性。以下是 Swagger2 中常用的注解及其作用：

---

官方网站：https://swagger.io/

1. 核心注解

@Api

• 作用：标注在控制器类上，描述整个控制器的作用。
• 常用属性：
  • tags：控制器分组标签（替代旧版 value）。
  • description：控制器详细描述。
• 示例：

  @Api(tags = "用户管理", description = "用户相关操作")
  @RestController
  @RequestMapping("/user")
  public class UserController { ... }
  

@ApiOperation

• 作用：标注在具体方法上，描述接口的功能。
• 常用属性：
  • value：接口简要说明。
  • notes：接口详细描述。
  • response：接口返回类型。
• 示例：

  @ApiOperation(value = "创建用户", notes = "根据用户对象创建新用户")
  @PostMapping
  public User createUser(@RequestBody User user) { ... }
  

@ApiParam

• 作用：标注在方法参数上，描述接口参数的信息。
• 常用属性：
  • name：参数名称（默认自动读取参数名）。
  • value：参数说明。
  • required：是否必填。
• 示例：

  @GetMapping("/{id}")
  public User getUser(@ApiParam(name = "id", value = "用户ID", required = true) @PathVariable Long id) { ... }
  

---

2. 响应相关注解

@ApiResponse

• 作用：描述接口的响应状态码和说明，通常与 @ApiResponses 组合使用。
• 常用属性：
  • code：HTTP 状态码（如 200, 404）。
  • message：状态码对应的说明。
• 示例：

  @ApiResponses({@ApiResponse(code = 200, message = "请求成功"),@ApiResponse(code = 404, message = "用户不存在")
  })
  @GetMapping("/{id}")
  public User getUser(@PathVariable Long id) { ... }
  

---

3. 模型相关注解

@ApiModel

• 作用：标注在模型类上（如 DTO、VO），描述数据模型。
• 常用属性：
  • value：模型名称。
  • description：模型详细描述。
• 示例：

  @ApiModel(value = "用户实体", description = "用户基本信息")
  public class User {// ...
  }
  

@ApiModelProperty

• 作用：标注在模型类的字段上，描述字段属性。
• 常用属性：
  • value：字段说明。
  • example：示例值。
  • required：是否必填。
• 示例：

  @ApiModelProperty(value = "用户名", example = "张三", required = true)
  private String username;
  

---

4. 参数高级注解

@ApiImplicitParam

• 作用：描述非基于方法参数绑定的请求参数（如通过 HttpServletRequest 获取的参数）。
• 常用属性：
  • name：参数名。
  • value：参数说明。
  • dataType：数据类型（如 String、int）。
  • paramType：参数传递方式（如 query、path、header）。
• 示例：

  @ApiImplicitParams({@ApiImplicitParam(name = "token", value = "认证令牌", dataType = "String", paramType = "header")
  })
  @GetMapping("/info")
  public User getUserInfo(HttpServletRequest request) { ... }
  

---

5. 其他常用注解

@ApiIgnore

• 作用：忽略某个接口或参数，不生成到文档中。
• 示例：

  @ApiIgnore  // 忽略此接口
  @GetMapping("/internal")
  public String internalApi() { ... }
  

@ApiImplicitParams

• 作用：组合多个 @ApiImplicitParam 注解。
• 示例：

  @ApiImplicitParams({@ApiImplicitParam(name = "page", value = "页码", dataType = "int", paramType = "query"),@ApiImplicitParam(name = "size", value = "每页数量", dataType = "int", paramType = "query")
  })
  @GetMapping("/list")
  public List<User> getUsers(int page, int size) { ... }
  

---

6.总结

1.关键区别说明

‌@ApiImplicitParam vs @ApiParam‌：
前者用于非实体类参数(如路径参数、查询参数),后者常用于配合 @RequestParam 或 @PathVariable

‌@ApiModelProperty vs @ApiParam‌：
前者用于实体类字段，后者用于方法参数‌

2.Swagger UI 访问路径
原生UI界面 springfox-swagger-ui
http://localhost:8080/swagger-ui.html
更美观的界面 swagger-bootstrap-ui
http://localhost:8080/doc.html

3.创建swagger配置类
通过合理使用这些注解，可以生成清晰、交互性强的 API 文档，并进行接口分组。示例配置如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.controller")).paths(PathSelectors.any()).build().apiInfo(apiInfo());}// 用户管理分组  @Bean  public Docket userApi() {  return newDocket(DocumentationType.SWAGGER_2)  .groupName("用户管理")  .apiInfo(apiInfo())  .select()  .apis(RequestHandlerSelectors.basePackage("com.example.user.controller"))  .paths(PathSelectors.any())  .build();  }  // 订单管理分组  @Bean  public Docket orderApi() {  return newDocket(DocumentationType.SWAGGER_2)  .groupName("订单管理")  .apiInfo(apiInfo())  .select()  .apis(RequestHandlerSelectors.basePackage("com.example.order.controller"))  .paths(PathSelectors.any())  .build();  } private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API 文档").description("项目接口说明").version("1.0").build();}
}

使用时需添加 Swagger2 依赖（Maven）：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency><!--UI界面 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency><!--更美观的UI界面，跟上面的UI界面二选一即可 -->
<dependency>  <groupId>com.github.xiaoymin</groupId>  <artifactId>swagger-bootstrap-ui</artifactId>  <version>1.9.6</version>  
</dependency> 

特别说明：

还有一种更美观的UI界面，即Knife4j.
Knife4j 的前身是 swagger-bootstrap-ui，前身 swagger-bootstrap-ui 是一个纯 swagger-ui 的 ui 皮肤项目。

参考文档：https://blog.csdn.net/xhmico/article/details/131701790
官方文档：https://doc.xiaominfo.com/docs/quick-start
开源地址：https://gitee.com/xiaoym/knife4j