Class ValueObjectSchemaTransformer

Namespace: AdCodicem.ValueObjects.OpenApi
Assembly: AdCodicem.ValueObjects.OpenApi.dll

Documents a value object as its underlying type rather than as an object with a Value property.

public sealed class ValueObjectSchemaTransformer : IOpenApiSchemaTransformer

Inheritance

object ← ValueObjectSchemaTransformer

Implements

IOpenApiSchemaTransformer

Inherited Members

object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Remarks

Schema generation is driven by JsonTypeInfo, and a type carrying a custom converter is opaque to it, so a value object would otherwise appear as an empty schema. This transformer fills it in from the the generator captured, which means the pattern, bounds, length and accepted values published in the document are literally the ones the type enforces — they cannot drift. What each rule becomes is shared with ValueObjectJsonSchema, in AdCodicem.ValueObjects.Json, which describes a value object alike in a JSON Schema System.Text.Json exports, and the whole description of a value object with the Swashbuckle filters of AdCodicem.ValueObjects.Swashbuckle, which build on the same object model.

A value object written by hand is documented as well, from the schema it declares, through the descriptor the registry builds by reflection when nothing registered the type, as the model binder and the FluentValidation rules resolve it. It runs while the document is built, not per request.

A value object over a number honours as the built-in converter of its underlying type does, and is documented as System.Text.Json documents that type under the same options: as a number or a string matching a numeric pattern when a number may be written or read as text, and, over a or a , with the named literals its bounds let through.

A value object is described wherever it appears: as a route, query or header parameter, which ASP.NET Core hands over as text, with the value object's schema in place; as the element of a collection or the value of a dictionary, which System.Text.Json leaves out, with a reference to its component; and as the key of a dictionary, in propertyNames, as the text the key is written in.

Text a member or a parameter holds to a value object's rules under is described as that text: a string with the value object's pattern, lengths, format, bounds, example and known values, whatever its underlying type, and each element of a collection of such text. The attribute is read on the property, on the constructor parameter of the same name, where MVC requires it on a record, and on the parameter of a minimal API or an MVC action, a member of a model MVC binds from the query string included. A rule the declaration states as well, such as [StringLength], is kept where it is the stricter.

A closed value set lists its values in enum, and their names, the names of the known values, in the x-enum-varnames, x-enumNames and x-ms-enum extensions, which client generators name the members of their enumeration after; x-ms-enum carries the description of each value declared with one.

Methods

TransformAsync(OpenApiSchema, OpenApiSchemaTransformerContext, CancellationToken)

Transforms the specified OpenAPI schema.

public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)

Parameters

schema OpenApiSchema

The to modify.

context OpenApiSchemaTransformerContext

The associated with the .

cancellationToken CancellationToken

The cancellation token to use.

Returns

Task

The task object representing the asynchronous operation.