隐藏 Swagger API 文档中的端点

2023-12-12

1、概览

在 Spring Boot 中使用 Swagger 文档时，有时候需要隐藏端点。最常见的情况就是，该端点还在开发中。或者是有一些内部端点，不想暴露给用户。

本文将带你了解如何在 Swagger API 文档中隐藏端点。

2、使用 @ApiIgnore 隐藏端点

可以在 Handler 方法上添加 @ApiIgnore 注解来隐藏端点：

@ApiIgnore
@ApiOperation(value = "This method is used to get the author name.")
@GetMapping("/getAuthor")
public String getAuthor() {
    return "Umang Budhwar";
}

3、使用 @ApiOperation 隐藏端点

也可以使用 @ApiOperation 来隐藏端点：

@ApiOperation(value = "This method is used to get the current date.", hidden = true)
@GetMapping("/getDate")
public LocalDate getDate() {
    return LocalDate.now();
}

将 @ApiOperation 注解的 hidden 属性设置为 true，即可使 Swagger 忽略该端点。

4、使用 @ApiIgnore 隐藏所有端点

如果在 Controller 类上使用 @ApiIgnore 注解，那么会隐藏该 Controller 下的所有端点：

@ApiIgnore
@RestController
public class RegularRestController {
    // 代码省略 。。。
}

注意，这会从文档中隐藏 Controller 本身。

6、使用 @Hidden 隐藏端点

如果使用的是 OpenAPI v3，则可以使用 @Hidden 注解隐藏端点：

@Hidden
@GetMapping("/getAuthor")
public String getAuthor() {
    return "Umang Budhwar";
}

7、使用 @Hidden 隐藏所有端点

同样，也可以在 Controller 类上使用 @Hidden 注解，以隐藏所有端点：

@Hidden
@RestController
public class RegularRestController {
    // 业务代码 。。。
}

这也会从文档中隐藏 Controller。

注意：只有在使用 OpenAPI 时才能使用 @Hidden。Swagger v3 对该注解的支持仍在进行中。

8、总结

本文介绍了如何在 Swagger 文档中隐藏单个端点或者所有端点。

Ref：https://www.baeldung.com/spring-swagger-hiding-endpoints