REST Top

Get started with Spring 5 and Spring Boot 2, through the reference Learn Spring course:

>> CHECK OUT THE COURSE

1. Overview

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.

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.

2. Hiding an Endpoint with @ApiIgnore

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

@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

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

@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.

4. Hiding All Endpoints with @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
@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

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

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

7. Hiding All Endpoints with @Hidden

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

@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.

8. Conclusion

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.

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.

REST bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course :

>> CHECK OUT THE COURSE
REST footer banner
2 Comments
Oldest
Newest
Inline Feedbacks
View all comments
Comments are closed on this article!