介绍
@Tags
是 Swagger Core 库中的一个注解,用于在 OpenAPI 3.0 规范中为 API 方法或类添加多个标签(Tag)。它是 @Tag
注解的容器注解(Container Annotation),允许在同一个类或方法上定义多个标签。
源代码
package io.swagger.v3.oas.annotations.tags;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Tags {
Tag[] value() default {};
}
注解属性
value
-
类型:
Tag[]
-
说明:包含多个
@Tag
注解的数组,用于定义多个标签。 -
示例:
value = {
@Tag(name = "demo Management", description = "APIs for demo"),
@Tag(name = "demo Authentication", description = "APIs for demo authentication")
}
使用场景
@Tags
注解通常用于以下场景:
为类添加多个标签
将 @Tags
注解添加到类上,表示该类下的所有 API 方法都属于这些标签
与 @Tag
的区别
-
@Tag
是单个标签的注解,只能定义一个标签。 -
@Tags
是@Tag
的容器注解,可以定义多个标签。
在 Java 8 及以上版本中,@Tag
注解被标记为 @Repeatable
,因此可以直接在同一个类或方法上多次使用 @Tag
,而不需要使用 @Tags
。
示例代码
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.tags.Tags;
import org.springframework.web.bind.annotation.*;
@Tags({
@Tag(name = "Demo Management", description = "APIs for Demo"),
@Tag(name = "Demo Authentication", description = "APIs for Demo authentication")
})
@RestController
@RequestMapping("/demo")
public class DemoController {
@Tags({
@Tag(name = "Demo Management"),
@Tag(name = "Authentication")
})
@Operation(summary = "Login Demo")
@PostMapping("/login")
public ResponseEntity<String> login(@RequestBody LoginRequest request) {
// Method implementation
}
@Tag(name = "Demo Management")
@Operation(summary = "Get Demo by ID")
@GetMapping("/{id}")
public User getDemo(@PathVariable Long id) {
// Method implementation
}
}