Document Transformers
Namespace: RA.Utilities.OpenApi.DocumentTransformers
The main purpose of these transformers is to automate common and repetitive tasks, enforce consistency, and keep your API endpoint definitions clean. Instead of manually annotating every endpoint, you can apply these transformations globally.
Here's a breakdown of the transformers included in this package and their purposes:
DocumentInfoTransformer
This populates the top-level information of your OpenAPI document, such as the title, version, and description, directly from your appsettings.json configuration.
This allows you to update your API's documentation details without changing any code.
BearerSecurityDocumentTransformer
It automatically adds a "Bearer" security scheme to your OpenAPI document if it detects that JWT Bearer authentication is registered in your application. This enables the "Authorize" button in the Swagger UI, simplifying the testing of protected endpoints.
HeadersParameterTransformer
his transformer adds common headers, like x-request-id for correlation and tracing, to every API operation.
This is particularly useful for microservices where tracking requests across different services is essential.
PolymorphismDocumentTransformer
This transformer correctly represents inheritance in polymorphic types (a base class with several derived classes) within the OpenAPI schema.
It uses the oneOf and discriminator keywords to help client-side code generators understand the API's data structure.
📄️ BearerSecurityDocumentTransformer
The BearerSecurityDocumentTransformer is an IOpenApiDocumentTransformer that automatically adds a "Bearer" security scheme to your OpenAPI document. This enables the "Authorize" button in the Swagger UI, allowing users to easily test protected endpoints.
📄️ HeadersParameterTransformer
The HeadersParameterTransformer is an IOpenApiDocumentTransformer that automatically adds common headers to every operation in your OpenAPI document.
📄️ PolymorphismDocumentTransformer
The PolymorphismDocumentTransformer is an IOpenApiDocumentTransformer that enables correct OpenAPI documentation for polymorphic types (a base class with one or more derived classes). It modifies the OpenAPI document to use the oneOf and discriminator keywords, which allows API clients and code generators to understand and handle the inheritance structure.
📄️ DocumentInfoTransformer
The DocumentInfoTransformer is an IOpenApiDocumentTransformer that populates the top-level information of your OpenAPI document (like title, version, and description) directly from your appsettings.json configuration.