A name–value pair associates a named key with its corresponding value. The key identifies the metadata or property, while the value supplies its content. In a NoSQL document, flexible schemas use collections of these pairs to represent a record and related information. section 4.1.1
In API documentation, custom pairs extend generated JSON schemas. A reusable C# attribute stores a string key and value, and a schema filter copies each pair into the schemas for annotated properties, parameters, or other exposed API elements. section 11.3.4
Listing 11.7 CustomKeyValueAttribute
namespace MyBGList.Attributes
{
[AttributeUsage(
AttributeTargets.Property | AttributeTargets.Parameter,
AllowMultiple = true)]
public class CustomKeyValueAttribute : Attribute
{
public CustomKeyValueAttribute(string? key, string? value)
{
Key = key;
Value = value;
}
public string? Key { get; set; }
public string? Value { get; set; }
}
}
The attribute accepts a key and value, targets properties and parameters, and permits repeated use so one element can receive multiple pairs. section 11.3.4
Listing 11.8 CustomKeyValueFilter
using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
namespace MyBGList.Attributes
{
public class CustomKeyValueFilter : ISchemaFilter
{
public void Apply(
OpenApiSchema schema,
SchemaFilterContext context)
{
var caProvider = context.MemberInfo
?? context.ParameterInfo
as IcustomAttributeProvider; #1
var attributes = caProvider?
.GetCustomAttributes(true)
.OfType<CustomKeyValueAttribute>(); #2
if (attributes != null) #3
{
foreach (var attribute in attributes)
{
schema.Extensions.Add(
attribute.Key,
new OpenApiString(attribute.Value)
);
}
}
}
}
}
The schema filter retrieves applied attributes and adds each pair as an OpenAPI extension during schema generation. section 11.3.4
Adding custom OpenAPI metadata
Applying [CustomKeyValue("x-test-1", "value 1")] and [CustomKeyValue("x-test-2", "value 2")] to UserName produces matching x-test-1 and x-test-2 entries in the LoginDTO schema. Applying x-test-3 to an endpoint parameter places it in that operation's parameter schema.
