swagger注解之@ApiOperation

链接: swagger学习一.
链接: swagger学习二.

@ApiOperation() 用于方法；表示一个http请求的操作

@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）；其他参数可参考源码；

• value：对该操作进行简单的描述，尽量控制在120字符以内。
• notes：对操作的详细描述。
• httpMethod：指定操作使用的HTTP方法类型，可选值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”。
• tags：用来给操作打标签，Swagger UI 将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag 的操作列表。（就是分组）

1、示例1：

@ApiOperation(value = "验证 @ApiOperation 注解",
        notes = "验证 @ApiOperation 注解 value 和 notes 属性的用法",
        httpMethod = "POST")
@RequestMapping("/demo1")
public void demo1() {
    //...
}

运行后的效果图如下：

注意：@ApiOperation 注解只能应用于方法上面，这是因为在它的源码上面进行了声明。代码如下：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiOperation {
    //...
}

2、示例2：

@ApiOperation(value = "验证 tags 用法",
        notes = "验证 @ApiOperation 注解的 tags 属性的用法",
        httpMethod = "GET",
        tags = {"tag1", "tag2", "tag3"})
@RequestMapping("/demo2")
public void demo2() {}

效果图如下：

3、示例3：
response：指定操作的响应的类型，手动设置此属性将覆盖任何自动生成的数据类型。如果使用的值是一个原始数据类型（如：int、long），则将使用相应的原始数据类型对象，默认为 Void.class（注意：如果返回类型是 List、Map、Set 请使用 responseContainer 属性）。

// 不指定返回类型
@ApiOperation(value = "验证 response 用法",
        notes = "验证 @ApiOperation 注解的 response 属性的用法",
        httpMethod = "GET")
@RequestMapping("/demo3")
public User demo3() {
    return User.builder().build();
}
 
// 手动指定 response，覆盖系统自动生成的类型
@ApiOperation(value = "验证 response 用法",
        notes = "验证 @ApiOperation 注解的 response 属性的用法",
        httpMethod = "GET",
        response = User.class)
@RequestMapping("/demo4")
public long demo4() {
    return System.currentTimeMillis();
}
 
// 手动指定
@ApiOperation(value = "验证 response 用法",
        notes = "验证 @ApiOperation 注解的 response 属性的用法",
        httpMethod = "GET",
        response = User.class)
@RequestMapping("/demo5")
public User demo5() {
    return User.builder().build();
}

效果图如下：