Swagger学习⑥——@Hidden注解

介绍

@Hidden 注解是 Swagger Core 库的一部分，属于 Swagger/OpenAPI 3.x。它用于在生成 OpenAPI 文档时隐藏特定的 API 操作（方法）或类。

作用

@Hidden 注解的主要作用是标记某个方法或类，使其不会出现在生成的 OpenAPI 文档中。这在以下场景中非常有用：

• 某些内部接口或方法不希望暴露给外部用户。

• 某些接口尚未完成或处于测试阶段，暂时不需要公开。

• 某些接口仅用于内部调试，不需要对外公开。

使用范围

@Hidden 注解可以用于以下位置：

1. 类级别：隐藏整个控制器类，该类中的所有方法都不会出现在 OpenAPI 文档中。

2. 方法级别：隐藏特定的方法，该方法不会出现在 OpenAPI 文档中。

源代码

package io.swagger.v3.oas.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.TYPE, ElementType.FIELD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Hidden {

}

示例代码

隐藏整个控制器类

import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.RestController;

// 隐藏整个控制器类
@Hidden 
@RestController
public class DemoInternalController {

    @GetMapping("/internalDemo")
    public String internalDemoMethod() {
        return "This is an internal Demo method.";
    }

}

隐藏特定方法

import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/demos")
    public String getDemos() {
        return "List of Demo";
    }

    // 隐藏该方法
    @Hidden 
    @GetMapping("/internal/demo")
    public String getInternalDemos() {
        return "Internal list of demos";
    }
}