Class ValueObjectSwaggerGenExtensions
Namespace: AdCodicem.ValueObjects.Swashbuckle
Assembly: AdCodicem.ValueObjects.Swashbuckle.dll
Wires value object support into Swashbuckle's document generation.
public static class ValueObjectSwaggerGenExtensions
Inheritance
object ← ValueObjectSwaggerGenExtensions
Inherited Members
object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.MemberwiseClone(), object.ReferenceEquals(object?, object?), object.ToString()
Methods
AddValueObjects(SwaggerGenOptions)
Documents value objects as their underlying types, with the rules declared on them.
public static SwaggerGenOptions AddValueObjects(this SwaggerGenOptions options)
Parameters
options SwaggerGenOptions
Swashbuckle's options, from AddSwaggerGen.
Returns
The same options, so calls can be chained.
Remarks
Swashbuckle describes a type from its public properties, blind to the converter a value object travels through,
so a value object would otherwise be documented as an object with a value property, the very wrapper the
value object keeps off the wire. A schema filter describes it as its underlying type instead, with the pattern,
bounds, lengths, example and accepted values declared on it, as AdCodicem.ValueObjects.OpenApi describes it on the
built-in stack, and a parameter filter makes a minimal API's route, query or header parameter refer to its
component, as an MVC action's already does. A value object written by hand, a construction of a generic value
object, and the value object a MapType maps are described too.
The examples and known values are written as the minimal API options of System.Text.Json write them. A number
System.Text.Json writes as a JSON number is documented as Swashbuckle documents the underlying type in the same
document, as a number, whatever those options let be read from text; a 128-bit integer, which travels as a JSON
string, stays a string. A nullable member, element or dictionary value is described in place with null
allowed, as Swashbuckle describes a nullable primitive, though with the rules of its type alone, as Swashbuckle
describes the non-nullable one, and the enumeration of a closed set is named after its component, under the
identifier CustomSchemaIds gives it when an application chose one.
Call it after IncludeXmlComments: Swashbuckle runs its schema filters in the order they were added, and its
XML comments filter would otherwise replace the description of a value object with the type's summary, losing the
sentence that states the bounds of a value written as text. Called twice, it adds each filter once, and the
options of the last call win.
AddValueObjects(SwaggerGenOptions, JsonSerializerOptions)
Documents value objects as their underlying types, with the rules declared on them, writing their examples and known values with the given serializer options rather than with the minimal API ones.
public static SwaggerGenOptions AddValueObjects(this SwaggerGenOptions options, JsonSerializerOptions serializerOptions)
Parameters
options SwaggerGenOptions
Swashbuckle's options, from AddSwaggerGen.
serializerOptions JsonSerializerOptions
The options the application writes value objects with, for an application whose MVC and minimal API options differ.
Returns
The same options, so calls can be chained.
Remarks
A number System.Text.Json writes as a JSON number is still documented as a number, whatever