1. Overview

1.概述

While creating Swagger documentation, we often need to hide endpoints from being exposed to end-users. The most common scenario to do so is when an endpoint is not ready yet. Also, we could have some private endpoints which we don’t want to expose.

在创建Swagger文档时，我们经常需要隐藏端点，不让其暴露在终端用户面前。最常见的情况是当一个端点还没有准备好时。另外，我们可能有一些私人的端点，我们不想暴露出来。

In this short article, we’ll have a look at how we can hide endpoints from Swagger API documentation. To achieve this, we’ll be using annotations in our controller class.

在这篇短文中，我们将看看如何从Swagger API文档中隐藏端点。为了实现这一目标，我们将在控制器类中使用注解。

2. Hiding an Endpoint with @ApiIgnore

2.用@ApiIgnore隐藏一个端点

The @ApiIgnore annotation allows us to hide an endpoint. Let’s add this annotation for an endpoint in our controller:

@ApiIgnore注解允许我们隐藏一个端点。让我们为我们的控制器中的一个端点添加这个注解。

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

3. Hiding an Endpoint with @ApiOperation

3.用@ApiOperation隐藏一个端点

Alternatively, we can use @ApiOperation to hide a single endpoint:

另外，我们可以使用@ApiOperation来隐藏单个端点。

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

Notice that we need to set the hidden property to true to make Swagger ignore this endpoint.

注意我们需要将hidden属性设置为true以使Swagger忽略这个端点。

4. Hiding All Endpoints with @ApiIgnore

4.用@ApiIgnore隐藏所有端点

Nonetheless, sometimes we need to hide all the endpoints of a controller class. We can achieve this by annotating the controller class with @ApiIgnore:

尽管如此，有时我们需要隐藏一个控制器类的所有端点。我们可以通过给控制器类加上@ApiIgnore的注解来实现。

@ApiIgnore
@RestController
public class RegularRestController {
    // regular code
}

It is to be noted that this will hide the controller itself from the documentation.

需要注意的是，这将把控制器本身从文档中隐藏起来。。

6. Hiding an Endpoint with @Hidden

6.用@Hidden隐藏一个端点

If we’re using OpenAPI v3, we can hide an endpoint using the @Hidden annotation:

如果我们使用OpenAPI v3，我们可以使用@Hidden注解隐藏一个端点。

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

7. Hiding All Endpoints with @Hidden

7.用@Hidden隐藏所有端点

Similarly, we can annotate the controller with @Hidden to hide all the endpoints:

同样地，我们可以用@Hidden来注释控制器，以隐藏所有的端点。

@Hidden
@RestController
public class RegularRestController {
    // regular code
}

This will also hide the controller from the documentation.

这也将从文档中隐藏控制器。

Note: We can only use @Hidden when we’re using OpenAPI. The support for this annotation in Swagger v3 is still in progress.

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

8. Conclusion

8.结语

In this tutorial, we’ve seen how we can hide the endpoints from Swagger documentation. We discussed how to hide a single endpoint and also all the endpoints of a controller class.

在本教程中，我们已经看到了如何从Swagger文档中隐藏端点。我们讨论了如何隐藏单个端点以及一个控制器类的所有端点。

As always, the complete code for the Swagger examples is available over on GitHub, and the OpenAPI v3 examples are available over on GitHub as well.

一如既往，Swagger 示例的完整代码可在 GitHub 上获取，而 OpenAPI v3 示例也可在 GitHub 上获取。