611 字
3 分钟
Swagger2常用注解
1. 类级别注解
@Api
- 描述：用于标注Controller类，表示这是一个Swagger资源
- 常用参数：
tags: API分组标签value: API描述(已过时，建议使用description)description: API详细描述produces: 指定返回的内容类型consumes: 指定接收的内容类型
@Api(tags = "用户管理", description = "用户相关操作接口")@RestController@RequestMapping("/users")public class UserController { // ...}2. 方法级别注解
@ApiOperation
- 描述：描述一个API操作
- 常用参数：
value: 简要描述notes: 详细说明response: 返回类型httpMethod: HTTP方法类型produces: 输出MIME类型consumes: 输入MIME类型
@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")@PostMappingpublic User createUser(@RequestBody User user) { // ...}@ApiResponses 和 @ApiResponse
- 描述：描述方法返回值的状态码和说明
- 常用参数：
code: HTTP状态码message: 描述信息response: 返回类型
@ApiResponses({ @ApiResponse(code = 200, message = "成功", response = User.class), @ApiResponse(code = 400, message = "无效的用户输入"), @ApiResponse(code = 500, message = "服务器内部错误")})@GetMapping("/{id}")public User getUser(@PathVariable Long id) { // ...}3. 参数级别注解
@ApiParam
- 描述：描述单个参数
- 常用参数：
name: 参数名称value: 参数说明required: 是否必填example: 示例值
@GetMapping("/{id}")public User getUser( @ApiParam(name = "id", value = "用户ID", required = true, example = "1") @PathVariable Long id) { // ...}@ApiImplicitParams 和 @ApiImplicitParam
- 描述：描述非JAX-RS标准的参数(如header参数)
- 常用参数：
name: 参数名称value: 参数说明required: 是否必填dataType: 数据类型paramType: 参数类型(query/path/header/body/form)
@ApiImplicitParams({ @ApiImplicitParam(name = "token", value = "认证token", required = true, dataType = "string", paramType = "header")})@GetMapping("/info")public UserInfo getUserInfo() { // ...}4. 模型注解
@ApiModel
- 描述：描述模型类
- 常用参数：
value: 模型名称description: 模型描述
@ApiModel(value = "用户实体", description = "用户信息描述")public class User { // ...}@ApiModelProperty
- 描述：描述模型属性
- 常用参数：
value: 字段说明example: 示例值required: 是否必填hidden: 是否隐藏
@ApiModelProperty(value = "用户名", example = "admin", required = true)private String username;
@ApiModelProperty(value = "密码", hidden = true)private String password;5. 其他注解
@ApiIgnore
- 描述：忽略某个元素，不生成文档
- 可用于类、方法或参数上
@ApiIgnorepublic void someHelperMethod() { // 这个方法不会出现在API文档中}配置示例
完整的Swagger配置类示例：
@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build() .apiInfo(apiInfo()); }
private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文档") .description("系统API接口文档") .version("1.0") .build(); }}Swagger2常用注解
https://mj3622.github.io/posts/编程实践/knife4j常用注解/