How to Hide Specific Mappings in Swagger UI Documentation for Spring Boot

Discover two effective methods to `exclude specific endpoints` from your Swagger documentation when using Spring Boot
---
This video is based on the question https://stackoverflow.com/q/68171707/ asked by the user 'Mahesh Yadav' ( https://stackoverflow.com/u/7262584/ ) and on the answer https://stackoverflow.com/a/68211176/ provided by the user 'Razvan' ( https://stackoverflow.com/u/7611661/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, latest updates/developments on topic, comments, revision history etc. For example, the original title of the Question was: How to hide only one mapping from swagger ui documentation if I more than one mapping for method in Spring boot

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to write me at vlogize [AT] gmail [DOT] com.
---
How to Hide Specific Mappings in Swagger UI Documentation for Spring Boot

When developing applications with Spring Boot, documentation is crucial for API understanding and usability. However, there might be instances when you want to exclude specific mapping endpoints from appearing in the Swagger UI documentation. This guide will guide you through the steps to hide one particular mapping, while keeping others visible.

The Problem: Hiding One Mapping

Imagine you have a Spring Boot REST controller that serves multiple endpoints. For instance:

[[See Video to Reveal this Text or Code Snippet]]

In this example, the HomeController has two mappings: "/" and "/home". Let's say that you want to hide the "/home" mapping from the Swagger documentation. This may be necessary for several reasons, such as maintaining clean documentation or preventing information leakage.

Understanding the Limitations

Hiding specific mappings in a multi-mapped method using @ RequestMapping({url1, url2}) is not directly supported in Swagger. If you attempt to hide one of the endpoints using this mapping technique, you’ll find that Swagger will display all mappings by default. Fortunately, there are two effective strategies you can use to achieve your goal.

Solution 1: Split the Method

The first solution is to split your method into two separate methods. This allows you to annotate the method corresponding to the endpoint you want to hide using @ Operation(hidden=true). Here’s how you can implement this approach:

[[See Video to Reveal this Text or Code Snippet]]

Benefits of This Approach

Clear Separation: Each endpoint is clearly defined and can be managed independently.

Control Over Documentation: You have full control over which endpoints to show or hide.

Solution 2: Define Exception in Swagger Config

Another method involves configuring Swagger to exclude specific endpoints from documentation. If you’re using Springdoc OpenAPI (Swagger 3), you can define this in your configuration file. Here’s a straightforward example:

[[See Video to Reveal this Text or Code Snippet]]

Advantages of This Configuration

Single Point Management: You manage exclusions in one centralized configuration class, making it easier to handle larger applications with many endpoints.

Flexibility in API Design: You can easily adjust which endpoints to include or exclude without changing your controller methods.

Conclusion

Hiding specific mappings in Swagger UI documentation can be achieved using either of the two solutions outlined above. By splitting methods or adjusting the Swagger configuration, you can maintain a clean and organized API documentation that reflects your intended public interface.

Implement these strategies to ensure your Swagger documentation only includes the endpoints you want to showcase while keeping the unnecessary or sensitive ones hidden.

By employing these techniques, your API documentation will be user-friendly and tailored to your specific needs. Happy coding!