Skip to main content

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

arolariu.Backend.Core​

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

Classes​

SwaggerConfigurationService Class​

Provides centralized configuration for Swagger/OpenAPI documentation generation and UI presentation. This service configures the API documentation system used by the arolariu.ro public API, including custom schemas, authentication requirements, and presentation options.

internal static class SwaggerConfigurationService

Inheritance System.Object 🡒 SwaggerConfigurationService

Remarks​

This service is responsible for configuring three main aspects of Swagger integration:

  • Swagger generation options for OpenAPI specification creation
  • Swagger UI options for the interactive documentation interface
  • Swagger middleware options for serving the documentation

The generated documentation is available at the following endpoints:

The configuration includes:

  • JWT Bearer token authentication scheme
  • Custom type mappings for common response types
  • XML documentation comments integration
  • Enhanced UI features and customization

Methods​

SwaggerConfigurationService.GetSwaggerGenOptions() Method​

Configures comprehensive Swagger generation options for OpenAPI specification creation. This method defines the complete API documentation structure, including metadata, security schemes, custom type mappings, and XML documentation integration.

internal static System.Action<Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenOptions> GetSwaggerGenOptions();

Returns​

System.Action<Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenOptions>
An System.Action<> delegate that configures Swagger generation with custom schemas, authentication, and documentation settings.

Remarks​

This method configures extensive Swagger generation options:

API Metadata: - Sets comprehensive API information including title, version, and detailed description - Includes contact information and terms of service URL - Provides licensing information under MIT License

Security Configuration: - Defines JWT Bearer token authentication scheme - Configures security requirements for protected endpoints - Includes detailed authentication instructions for API consumers

Custom Type Mappings: - Maps Microsoft.AspNetCore.Http.IResult to standardized response schema with success, message, and data properties - Maps Microsoft.AspNetCore.Mvc.ProblemDetails to RFC 7807 problem details schema - Maps System.Collections.Generic.IEnumerable<> of key-value pairs to array schema for metadata responses

Documentation Enhancement: - Enables Swashbuckle annotations for enhanced API documentation - Uses inline definitions for enums to improve schema readability - Integrates XML documentation comments from compiled assembly - Applies custom document filters for additional processing

The generated OpenAPI specification follows OpenAPI 3.0 standards and includes comprehensive schema definitions for all API operations, enabling automatic client code generation and interactive testing.

SwaggerConfigurationService.GetSwaggerOptions() Method​

Provides basic Swagger middleware configuration options. This method returns default options for the Swagger JSON endpoint serving.

internal static Swashbuckle.AspNetCore.Swagger.SwaggerOptions GetSwaggerOptions();

Returns​

Swashbuckle.AspNetCore.Swagger.SwaggerOptions
A Swashbuckle.AspNetCore.Swagger.SwaggerOptions instance with default configuration for serving OpenAPI specifications.

Remarks​

This method currently returns default options without customization. It serves as a placeholder for future middleware-specific configuration needs, such as custom serialization settings or route templates.

SwaggerConfigurationService.GetSwaggerUIOptions() Method​

Configures the Swagger UI presentation options and behavior. This method customizes the interactive documentation interface for enhanced developer experience.

internal static Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIOptions GetSwaggerUIOptions();

Returns​

Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIOptions
A configured Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIOptions instance with customized settings for the API documentation interface.

Remarks​

The returned configuration includes the following customizations:

Navigation and Routing: - Sets the route prefix to empty string, making Swagger UI available at the root path - Configures the document title as "AROLARIU.RO Public API"

Authentication and Persistence: - Enables authorization persistence across browser sessions - Maintains user authentication state during documentation exploration

Display and Interaction Features: - Shows operation IDs for easier API reference - Displays request duration for performance monitoring - Enables syntax highlighting for better code readability - Configures model rendering to show examples by default - Sets appropriate expansion depth for nested models (2 levels) - Enables filtering capabilities for large API surfaces - Shows OpenAPI extensions and common extensions

SwaggerFilterService Class​

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.

internal sealed class SwaggerFilterService : Swashbuckle.AspNetCore.SwaggerGen.IDocumentFilter

Inheritance System.Object 🡒 SwaggerFilterService

Implements Swashbuckle.AspNetCore.SwaggerGen.IDocumentFilter

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​

SwaggerFilterService.AddExternalDocumentation(OpenApiDocument) Method​

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(Microsoft.OpenApi.OpenApiDocument swaggerDoc);

Parameters​

swaggerDoc Microsoft.OpenApi.OpenApiDocument

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

Exceptions​

System.ArgumentNullException
Thrown when swaggerDoc is null.

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.

SwaggerFilterService.Apply(OpenApiDocument, DocumentFilterContext) Method​

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(Microsoft.OpenApi.OpenApiDocument swaggerDoc, Swashbuckle.AspNetCore.SwaggerGen.DocumentFilterContext context);

Parameters​

swaggerDoc Microsoft.OpenApi.OpenApiDocument

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

context Swashbuckle.AspNetCore.SwaggerGen.DocumentFilterContext

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

Implements Apply(OpenApiDocument, DocumentFilterContext)

Exceptions​

System.ArgumentNullException
Thrown when swaggerDoc is null.

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.

SwaggerFilterService.FilterEndpointsFromDiscovery(OpenApiDocument) Method​

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(Microsoft.OpenApi.OpenApiDocument swaggerDoc);

Parameters​

swaggerDoc Microsoft.OpenApi.OpenApiDocument

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

Exceptions​

System.ArgumentNullException
Thrown when swaggerDoc is null.

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.

SwaggerFilterService.FilterTagsFromDiscovery(OpenApiDocument) Method​

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

private static void FilterTagsFromDiscovery(Microsoft.OpenApi.OpenApiDocument swaggerDoc);

Parameters​

swaggerDoc Microsoft.OpenApi.OpenApiDocument

The OpenAPI document.

// was this page useful?