Add description for OpenAPI schema references

[martincostello]

Apply description to properties using OpenAPI schema references when generating OpenAPI 3.1 documents.

Resolves #3759.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.01%. Comparing base (b2a9a92) to head (a924a58).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3860      +/-   ##
==========================================
+ Coverage   94.97%   95.01%   +0.03%     
==========================================
  Files         111      111              
  Lines        3903     3910       +7     
  Branches      789      788       -1     
==========================================
+ Hits         3707     3715       +8     
+ Misses        196      195       -1     

Flag	Coverage Δ
Linux	95.01% <100.00%> (+0.03%)	⬆️
Windows	95.01% <100.00%> (+0.03%)	⬆️
macOS	95.01% <100.00%> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR updates Swashbuckle’s OpenAPI 3.1 generation to include descriptive metadata alongside $ref schema references, targeting scenarios where OpenAPI 3.1 allows “$ref siblings” (e.g., adding description next to a $ref).

Changes:

• Populate selected schema metadata (e.g., Description) onto schema references returned from SchemaRepository.AddDefinition.
• Apply schema filters even when GenerateSchemaForType returns an OpenApiSchemaReference.
• Update Basic test site fixtures and OpenAPI 3.1 integration snapshots to reflect $ref-sibling description output.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SchemaRepository.cs	Adds metadata propagation from definitions to returned $ref schema references.
src/Swashbuckle.AspNetCore.SwaggerGen/SchemaGenerator/SchemaGenerator.cs	Applies schema filters to referenced schemas in the type-generation path.
test/WebSites/Basic/Controllers/SwaggerAnnotationsController.cs	Adds a SwaggerSchema description annotation intended to validate $ref sibling behavior.
test/WebSites/Basic/Controllers/DataAnnotationsController.cs	Adds a SwaggerSchema description annotation on an enum parameter intended to validate $ref sibling behavior.
test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/*/VerifyTests.*swaggerRequestUri=3.1*.verified.txt	Updates OpenAPI 3.1 snapshots to include description adjacent to $ref in several schema locations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.