Support for multiple API documents

[cosminstirbu]

Hi,

A subset of our endpoints are "administrative" endpoints that we'd like to avoid sharing them with the clients of our API.

Is there a way to have separate documents?

This would also help us when importing each definition into a separate API in Azure API Management.

Thank you,
Cosmin

[justinyoo]

@cosminstirbu Thanks for the issue! Let me rephrase your request based on my understanding.

For example, you've got 5 endpoints - 2 for admin purpose and 3 for consumer purpose. Then you only want to display 3 consumer ones, right?

In that case, you can add the OpenApiIgnoreAttribute decorator to your admin endpoints of 2. It's still working as endpoints but hidden from the Swagger UI. Is that what you're trying to achieve?

[cosminstirbu]

Hi @justinyoo

I'm actually interested in creating separate API documents, one for admin and one for consumer so I can import them independently as part of API Management and create two separate APIs (even if under the hood they are hosted in the same Azure Function).

Basically I'd like similar functionality with SwaggerDoc and DocInclusionPredicate from https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/95cb4d370e08e54eb04cf14e7e6388ca974a686e/src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

[justinyoo]

Although it's technically possible to implement, I'm reluctant to do so. Of course you can host as many endpoints as you want, but it's not what Azure Functions is supposed for.

It's more about architectural decision to make. Having two different instances - one for admin and the other for consumers makes more sense to me, as long as you use Azure Functions in a proper way.

[cosminstirbu]

I agree that from an architectural decision it would make more sense to split it (and in a normal scenario we would, but in our case we have only two admin endpoints that are used to delete test data generated by our semantic monitoring tests - so creating a dedicated Azure Function for them would come with a lot of ceremony - Terraform scripts, Azure Pipelines scripts, etc).

We are already using https://github.com/vitalybibikov/AzureExtensions.Swashbuckle to achieve this, but we would like to move to the official extension hosted on this repo.

As you've mentioned, Azure Functions can already be abused from an architectural standpoint, however I'm not sure that the solution would be to make the ecosystem surrounding it more opinionated, but rather allow the developers to pick their poison.

[jan-harders]

Would be a great feature to have support for more than one API document. Our team is struggeling with the same scenario: admin APIs. Very often, we have a thin layer/add-on to our domain services (each implemented by a single Azure Function App). E.g. we often need to trigger a post-deployment API endpoint, that runs some setup steps (ensure ressources are up and ready, event subscriptions to external services etc.). Moving this stuff to another Azure Function would not make it look nicer or cleaner from an architectural point of view. It would just produce overhead.

[justinyoo]

Related to #177