Fix/openapi schema xml comments ordering

[desjoerd]

Fix openapi schema xml comments handling for nested schemas

Fix applying annotations from xml on properties, nested and referenced schemas.

Description

Changes:

• Change the order of applying XML comments on schemas to make sure the property comment is leading (for applying the annotation on the reference)
• Add hoisting the description from the schema to the reference.

Remarks

⚠️ Currently fails because of the order SchemaTransformers are handled. The schema in the components will get the description from the last property. This is caused because of changing the order in the emitted schema transformer.

    Assert.Equal() Failure: Strings differ
           ↓ (pos 0)
Expected: "An address."
Actual:   "Visiting address."
           ↑ (pos 0)

Fixes #61965

[dotnet-policy-service]

Thanks for your PR, @@desjoerd. Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[martincostello]

Did you mean to include 14dd22b in this PR?

[desjoerd]

No, I am planning to rebase/cherry-pick when #62212 is merged. Otherwise I cannot run the unit tests 😅. I marked it as draft because it's also not completely correct at the moment. There needs to be some extra conditions to check whether it's a reference or not (to handle the two different descriptions, on the property with reference and on the schema in components).

I currently only get either the correct description on the reference and wrong on the schema or the other way around.

I am open to have a call about it, maybe tomorrow? Or to continue the discussion here or on the referenced issue.

[desjoerd]

I've done some more fiddling. With the current ordering of applying schema transformers and resolving references it's as far as I can see impossible to give a different description to the Schema Reference and the Schema itself.

Current behavior for the following classes:

/// <summary>
/// An address.
/// </summary>
public class AddressNested
{
    public string Street { get; set; }
}

public class Company
{
    /// <summary>
    /// Billing address.
    /// </summary>
    public AddressWithSummary BillingAddressClassWithSummary { get; set; }
    
    /// <summary>
    /// Visiting address.
    /// </summary>
    public AddressWithSummary VisitingAddressClassWithSummary { get; set; }
}

1. Apply schema transformer on Company
2. Apply schema transformer on AddressWithSummary with the PropertyInfo of BillingAddressClassWithSummary
3. Apply schema transformer on AddressWithSummary with the PropertyInfo of VisitingAddressClassWithSummary
4. Recursivly resolve schema references.

If we would copy the description from the AddressWithSummary schema it is either the description from the class or the last property referencing this schema.

I think the optional solution should be:
BillingAddress Property -> SchemaReference with description BillingAddress
VisitingAddress Property -> SchemaReference with description Visiting Address
AddressWithSummary Schema -> Schema with description An Address

Without changing the flow of applying schema transformers and resolving schema references we currently have to maybe go for:

if schema has metadata `x-schema-reference-id`:
    set description based on class
else
    if property has description
        set description based on property comment
    else
        set description based on class

This would mean that property comments are not used for schemas which become references, which in my opinion is the most "valid" option without changing the order.

If we would change the order I propose to go for something like:

1. Resolve Schema References on Company
2. Apply schema transformer on Company
   2.1. XmlCommentTransformer Set description on company schema based on class
   2.2. XmlCommentTransformer Apply descriptions on all properties of Company (which are already references)
3. Apply schema transformer on AddressWithSummary
   2.1. XmlCommentTransformer Set description on address schema based on class
   2.2. XmlCommentTransformer Apply descriptions on all properties of Address which is the Street property