Swagger / Open API — external documentation — customization / aggregation / central point of API docs (Swashbuckle.AspNetCore)

Motivation

You have one or more APIs and multiple consumers. Each consumer has different requirements and needs various endpoints from various APIs. Communication is typically solved by API GW or API Management. But the problem is: “How to resolve Open API (swagger) documentation”.

API Management contains typically tools for API documentation, but from my experience these tools are very limited. For example, Microsoft Azure API Management is not able to merge multiple APIs and expose selected endpoints.

Swagger tooling like Swashbuckle, NSwag, … has the possibility to customize API and use something like SchemaFilter or DocumentFilter, but it’s applicable just for internal controllers and endpoints, not for external APIs. Because an external API is not generated on your side.

The Goal of this article is to add external API docs to your documentation / re-use all or some parts of the existing api spec / create a central point of API documentation.