Skip to main content

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​

This 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.

HealthChecksDocumentTransformer​

This transformer documents the health check endpoints (/health and /alive) that MapHealthChecks maps without any API metadata, including their response schemas and a dedicated Health tag. The operations stay free of security schemes so the endpoints remain reachable without authentication.

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.

TagOperationTransformer​

Transforms the OpenAPI document by adding or updating tags with the configured descriptions.