Swagger学习三——@Tag 注解

介绍

@Tag 注解是 Swagger 中用于组织和分类 API 的重要工具。通过为类或方法添加标签，可以使 API 文档更加清晰和易于管理。结合 @Operation 等其他 Swagger 注解，可以生成功能强大且易于理解的 API 文档。

源码

package io.swagger.v3.oas.annotations.tags;

import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.extensions.Extension;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Repeatable;
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)
@Repeatable(Tags.class)
@Inherited
public @interface Tag {
    String name();

    String description() default "";

    ExternalDocumentation externalDocs() default @ExternalDocumentation;

    Extension[] extensions() default {};
}

注解属性

1. name

   • 类型：String

   • 说明：标签的名称，必填项。

   • 示例：

     name = "demo Management"

2. description

   • 类型：String

   • 说明：标签的描述信息，可选。

   • 示例：

     description = "APIs for managing demo "

3. externalDocs

   • 类型：ExternalDocumentation

   • 说明：指向外部文档的链接，可选。

   • 示例：

     externalDocs = @ExternalDocumentation(
         description = "demo ",
         url = "https://demo.com/demo-guide"
     )

4. extensions

   • 类型：Extension[]

   • 说明：扩展属性，用于添加自定义的 OpenAPI 扩展，可选。

5. 示例：

   extensions = {
       @Extension(name = "x-custom-feature", properties = {
           @ExtensionProperty(name = "enabled", value = "true")
       })
   }

   示例代码

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@Tag(name = "demo", description = "APIs for managing demo")
@RestController
@RequestMapping("/demo")
public class DemoController {


    @Operation(summary = "Get demoby ID")
    @GetMapping("/{id}")
    public User getDemo(@PathVariable Long id) {
        // Method implementation

    }


    @Operation(summary = "Login Demo")
    @PostMapping("/login")
    public ResponseEntity<String> login(@RequestBody LoginRequest request) {
        // Method implementation
    }

}

---

---

---