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 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 to hide the endpoints from Swagger documentation. We discussed how to hide a single endpoint and all the controller class endpoints.
As always, the complete code for the Swagger examples is available on GitHub, and the OpenAPI v3 examples are also available on GitHub.