Class SwaggerFilterService

Namespace

arolariu.Backend.Core.Domain.General.Services.Swagger

Assembly

arolariu.Backend.Core.dll

Implements custom filtering and enhancement logic for the OpenAPI/Swagger document generation. This service processes the generated Swagger document to remove internal endpoints from public documentation and adds external documentation references to improve API discoverability.

[ExcludeFromCodeCoverage]
[SuppressMessage("Design", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by the Swagger middleware during document generation.")]
internal sealed class SwaggerFilterService : IDocumentFilter

Inheritance

object

SwaggerFilterService

Implements

IDocumentFilter

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This document filter is automatically applied during Swagger document generation and performs two main functions:

Endpoint Filtering: Removes internal or infrastructure endpoints from the public API documentation to keep the documentation focused on business functionality. Filtered endpoints include health checks and utility endpoints that are not intended for public consumption.

Documentation Enhancement: Adds references to external documentation sources, providing API consumers with additional resources for comprehensive API understanding and integration guidance.

The filter is registered automatically through the Swagger configuration and executes during the document generation process, ensuring that the final OpenAPI specification reflects only the intended public API surface.

Methods

AddExternalDocumentation(OpenApiDocument)

Adds external documentation references to enhance the OpenAPI document with additional resources. This method provides API consumers with links to comprehensive documentation and integration guides.

private static void AddExternalDocumentation(OpenApiDocument swaggerDoc)

Parameters

swaggerDoc OpenApiDocument

The OpenApiDocument to enhance with external documentation references. The document's ExternalDocs property will be set with documentation links.

Remarks

External documentation provides additional value to API consumers by offering: - Detailed integration guides and tutorials - Comprehensive API usage examples - Architecture and design documentation - Best practices and implementation patterns

The external documentation is hosted separately from the interactive Swagger UI, allowing for more detailed explanations, code samples, and integration scenarios that complement the generated API reference.

Exceptions

ArgumentNullException

Thrown when swaggerDoc is null.

Apply(OpenApiDocument, DocumentFilterContext)

Applies the document filter transformations to the OpenAPI document. This method executes the filtering and enhancement logic to customize the generated API documentation.

public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)

Parameters

swaggerDoc OpenApiDocument

The OpenApiDocument being processed. This document contains the complete API specification including all discovered endpoints, schemas, and metadata.

context DocumentFilterContext

The DocumentFilterContext providing access to additional generation context, including type information, method descriptors, and configuration details.

Remarks

This method performs document transformations in the following order: 1. Filters out internal endpoints that should not appear in public documentation 2. Adds external documentation references to enhance API discoverability

The filtering ensures that only business-relevant endpoints are exposed in the public API documentation, while utility endpoints like health checks remain functional but undocumented.

Exceptions

ArgumentNullException

Thrown when swaggerDoc is null.

FilterEndpointsFromDiscovery(OpenApiDocument)

Removes specified internal endpoints from the public API documentation. This method ensures that infrastructure and utility endpoints are not exposed in the generated documentation.

private static void FilterEndpointsFromDiscovery(OpenApiDocument swaggerDoc)

Parameters

swaggerDoc OpenApiDocument

The OpenApiDocument from which to remove endpoints. The document's Paths collection will be modified to exclude filtered endpoints.

Remarks

The following endpoint categories are filtered from public documentation:

Health Check Endpoints (/health): These endpoints are used for infrastructure monitoring and load balancer health checks. While essential for operations, they don't provide business value to API consumers.

Utility Endpoints (/terms): Simple utility endpoints that serve static content or configuration values. These endpoints are typically used by the application itself rather than external integrators.

Filtered endpoints remain functional and accessible; they are simply excluded from the generated OpenAPI documentation to maintain focus on business functionality.

Exceptions

ArgumentNullException

Thrown when swaggerDoc is null.

FilterTagsFromDiscovery(OpenApiDocument)

Removes specified tags from the OpenAPI document. This ensures that internal or unwanted tags do not clutter the documentation.

private static void FilterTagsFromDiscovery(OpenApiDocument swaggerDoc)

Parameters

swaggerDoc OpenApiDocument

The OpenAPI document.