Add all "Annotations" to OpenApiSchemaReference

[desjoerd]

Currently we can only set description as an annotation on an OpenApiSchemaReference. With OpenApi 3.1 and Json Schema 2020-12 it's allowed to apply all annotations on a reference.

Annotations: https://json-schema.org/understanding-json-schema/reference/annotations#annotations
Spec: https://json-schema.org/draft/2020-12/json-schema-core#section-7.7.1.1
Meta data schema: json-schema.org/draft/2020-12/meta/meta-data

Why

When mapping nested classes to OpenApi in ASP.NET Core it uses comments to apply annotations like title, description, examples. But this is currently limited to only apply a description for a reference. In the [example](https://json-schema.org/understanding-json-schema/reference/annotations#annotations
Spec: https://json-schema.org/draft/2020-12/json-schema-core#section-7.7.1.1) provided in the spec it would be awesome to be able to set different metadata on properties (which become references).

Links

Related issue: dotnet/aspnetcore#61965

[baywet]

Hi @desjoerd
Thank you for using the SDK and for reaching out.

Here are the annotations that are already supported today:

• summary
• description

Here is what I can see is missing from the spec/documentation metadata:

• default
• title
• deprecated
• readOnly
• writeOnly
• examples

Am I missing anything?

[baywet]

Instructions for copilot:

1. Create a new OpenApiSchemaReferenceInformation that derives from OpenApiReference
2. In the OpenApiSchemaReferenceInformation type, add the following fields: default, title, deprecated, readOnly, writeOnly, examples
3. Add an additional generic parameter to BaseOpenApiReferenceHolder called U, with a constraint to derive from OpenApiReference
4. Update all existing usage of BaseOpenApiReferenceHolder to pass OpenApiReference as a value for that parameter
5. Update BaseOpenApiReferenceHolder Reference property to use that new generic parameter
6. Update the fields default, title, deprecated, readOnly, writeOnly, examples in OpenApiSchemaReference to behave like the summary field
7. Update the serialization and deserialization code to account for the OpenApiSchemaReferenceInformation type and its additional fields
8. Add the required unit tests

[desjoerd]

I think that's all.

One note though, summary doesn't exist in the spec 2020-12, and openapi 3.0 or below doesn't support annotations on references.

Aspnetcore openapi maps the /// <summary> comment to description