Use schema examples for XML comment examples

[pradeep-ramola]

Fixes #65181

Summary

Updates the OpenAPI XML comment source generator so schema-level <example> comments populate the OpenAPI examples collection instead of the singular example property.

This applies to XML examples on schema types and inline schema properties. Schema references already used Examples, so this makes generated schema output consistent with the requested OpenAPI shape.

Changes

• Changed generated XML comment schema transformers from schema.Example = ... to schema.Examples = [...].
• Updated source-generator assertions to validate Examples[0].
• Updated generated source snapshots.
• Updated OpenAPI integration snapshots for 3.0, 3.1, and 3.2 XML documents from example to examples.

Verification

Passed locally:

.\.dotnet\dotnet.exe build src/OpenApi/gen/Microsoft.AspNetCore.OpenApi.SourceGenerators.csproj --no-restore
.\.dotnet\dotnet.exe build src/OpenApi/src/Microsoft.AspNetCore.OpenApi.csproj --no-restore /p:BuildProjectReferences=false

I also attempted the focused source-generator test run locally, but the broader ASP.NET Core build graph requires repo-level generated JS/native assets in this checkout, including the Blazor Web.JS output and ANCM native build artifacts.

[pradeep-ramola]

@dotnet-policy-service agree

[Youssef1313]

@baywet I tried to look quickly at Microsoft.OpenApi usage of Examples, and in serialization I found it's happening only in WriteJsonSchemaKeywords (>= 3.1). But it's getting emitted in 3.0 here. Is there some code path I'm not seeing?

I can investigate myself if you don't have quick/immediate answer.

[pradeep-ramola]

Thanks for the review. I addressed the two FirstOrDefault() comments in the latest push: schema XML examples now populate schema.Examples from all parsed XML examples instead of only using the first one.

For the OpenAPI 3.0 snapshot question, I’ll leave that one to @baywet since it is about the Microsoft.OpenApi serialization behavior. Happy to update the snapshots/code if the expected 3.0 output should differ.

[baywet]

Here are a couple of elements of response for what the behaviour should be:

• version 2.X and 3.X only example (singular) existed, it's raw JSON that MUST validate the associated schema
• version 3.1+ examples (plural) was "imported from" JSON schema 2020-12, and it deprecates the singular field. The definition is here, it's an array and items in there should validate against the associated schema.

Now, in terms of serialization behaviour:

• examples (plural) MUST serialize as x-jsonschema-examples for OpenAPI 3.0 and 2.0. As examples (no extension) for 3.1+
• example (singular) MUST serialize as is across any version.

If that's not the current behaviour from Microsoft.OpenAPI, it needs to be fixed, go ahead and open an issue + PR.

Let me know if you have any additional comments or questions.

[Youssef1313]

@pradeep-ramola Would you like to do the investigation on Microsoft.OpenApi side? If not, let me know and I'll take care of it.

[baywet]

Created this issue. Sending copilot after it locally. microsoft/OpenAPI.NET#2969

[Youssef1313]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 2 pipeline(s).
3 pipeline(s) were filtered out due to trigger conditions.

[Youssef1313]

@pradeep-ramola The CI is failing here because there are test failures. I recommend waiting until a new version of Microsoft.OpenApi is released with some improvements that were done, get the new version flowing to the repo. Then you can merge latest main to your branch, run the tests locally, and update the snapshot tests to match the behavior so that the tests pass.

[pradeep-ramola]

@pradeep-ramola The CI is failing here because there are test failures. I recommend waiting until a new version of Microsoft.OpenApi is released with some improvements that were done, get the new version flowing to the repo. Then you can merge latest main to your branch, run the tests locally, and update the snapshot tests to match the behavior so that the tests pass.

Thanks for the clarification. I’ll wait until the Microsoft.OpenApi fix is released and flows into aspnetcore, then merge latest main into my branch, run the OpenAPI tests locally, and update the snapshots to match the new behavior.