Swagger @ApiOperation 详解

本文将详细介绍 Swagger 中的 @ApiOperation 注解，并通过实例演示如何正确使用它。@ApiOperation 注解是用来对方法或接口进行描述的工具。假如我们有如下代码：

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

运行后的效果如下：

值得注意的是，@ApiOperation 注解只能应用于方法上，这是因为它在源代码中被明确定义为方法级别的注解。

@ApiOperation 注解通常包含以下常用属性：

• value: 用于简要描述操作，最好不超过120个字符。
• notes: 提供操作的详细描述。
• httpMethod: 指定操作使用的HTTP方法类型，可选值包括 “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” 和 “PATCH”。
• tags: 用于给操作打标签，Swagger UI 将在操作列表下面展示标签列表，并将操作按标签分类展示。

以下是一个示例代码：

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

效果图如下：

上图中，我们创建了 tag1、tag2 和 tag3 三个 tag，然后在 demo2() 操作上面标记。

• 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();
}

效果图如下：

• responseContainer：声明包装响应的容器类型，有效值为“List”、“Set”或“Map”。任何其他值都将被忽略。
• responseReference：指定对响应类型的引用。指定的引用可以是本地引用，也可以是远程引用，将按原样使用，并将覆盖任何指定的 response() 类。
• nickname：对应于 “operationId” 字段。第三方工具使用 operationId 唯一标识此操作。在 Swagger 2.0 中，这不再是必需的，如果未提供，则将为空。
• produces：对应于操作的 “produces” 字段。
• consumes：对应于操作的 “consumes” 字段，接受内容类型的逗号分隔值。例如，“application/json,application/xml” 将建议此API 资源接受 JSON 和 XML 输入。
• protocols：设置此操作的特定协议（schemes），可用协议的逗号分隔值。可用的值：http，https，ws，wss。
• code：响应的 HTTP 状态代码。
• authorizations：对应于Operation Object的 “security” 字段。获取此操作的授权(安全需求)列表。服务器所需的授权数组，或者一个空授权值(如果没有设置)。
• hidden：从操作列表中隐藏操作。
• responseHeaders：响应提供的 HTTP 头字段列表。
• extensions：定义扩展属性

以上就是Swagger @ApiOperation 详解的全部内容。