Скачать или смотреть Customizing Swashbuckle Endpoint Paths for ASP.NET Core APIs

Learn how to customize your Swashbuckle-generated API documentation in ASP.NET Core by removing path prefixes effectively.
---
This video is based on the question https://stackoverflow.com/q/63539379/ asked by the user 'Lucas Lobosque' ( https://stackoverflow.com/u/1092723/ ) and on the answer https://stackoverflow.com/a/63643236/ provided by the user 'Lucas Lobosque' ( https://stackoverflow.com/u/1092723/ ) 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: Swashbuckle: Customize endpoint path (AspNetCore)

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.
---
Customizing Swashbuckle Endpoint Paths for ASP.NET Core APIs

When developing APIs with ASP.NET Core, especially when handling multiple subdomains, you may face a common issue: organizing different APIs under distinct paths while still needing to present a clean Swagger documentation. A specific challenge arises when you want to customize the Swagger JSON output to remove certain path prefixes without altering the actual endpoints accessible through API calls. In this post, we will explore how to achieve this by utilizing Document Filters in Swashbuckle.

The Problem

Imagine you’re managing several APIs that are differentiated by their subdomains:

user.api.example.com/v1/profile should correspond to api.example.com/user/v1/profile.

admin.api.example.com/v1/companies should correspond to api.example.com/admin/v1/companies.

In this scenario, you want the generated Swagger documentation to only show the following paths:

/v1/profile

/v1/companies

The core requirement is to remove the path prefixes (/user, /admin) from the Swagger JSON output while keeping the actual API endpoints intact. Can we configure a function in Swashbuckle to manipulate the Swagger output accordingly? Yes!

The Solution: Using Document Filters

To customize the API documentation, we can implement a Document Filter. This specialized filter allows us to manipulate the Swagger document before it's generated. Below is a step-by-step guide on how to create and implement a Document Filter that will modify the paths in your Swagger JSON.

Step 1: Create the Document Filter

Define a new class that implements the IDocumentFilter interface.

Override the Apply method to manipulate the swaggerDoc.Paths.

Here’s a simple implementation of the filter:

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

Step 2: Register the Document Filter

Next, you need to register this filter within the ConfigureServices method of your Startup.cs file. Here’s how you can do this:

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

Testing Your Configuration

Once you have implemented and registered the document filter, run your application and navigate to your Swagger UI (typically at /swagger). You should now see that the unwanted prefixes in the API paths have been removed, allowing your documentation to be cleaner and more organized.

Conclusion

Customizing your Swagger documentation can immensely improve the clarity of your API offerings, especially when dealing with multiple endpoints branching from different subdomains. By utilizing a Document Filter, developers can tailor the output to suit their needs without disrupting the actual API functionality.

Implement this solution in your ASP.NET Core applications to provide a better developer experience and help consumers understand your APIs less confusingly. Happy coding!