OpenAPI Controllers Sample with XML Comments

[max-lancaster]

This PR adds a comprehensive sample demonstrating XML documentation with OpenAPI in .NET 10, updates package versions, and improves the repository's .gitignore configuration for JetBrains Rider IDE support.

Changes Made

1. Add OpenAPI XML Controllers Sample

Added a new complete sample project under aspnetcore/fundamentals/openapi/samples/10.x/aspnet-openapi-xml-controllers/ that demonstrates:

• XML documentation integration with OpenAPI in .NET 10
• Controller-based API endpoints with comprehensive XML comments
• OpenAPI document generation with Scalar UI
• Example API requests using .http files
• Multi-project solution structure (API + Models projects)

Key Features:

• ProjectBoards Controller: Complete CRUD operations with XML documentation and OpenAPI tags
• Todos Controller: Comprehensive example showing XML doc comments, parameter descriptions, response types, and priority-based filtering
• External XML Documentation: AdditionalFiles.xml demonstrates adding external XML docs to OpenAPI
• Analyzer Control: Api-remove.csproj example showing how to disable the compile-time OpenAPI source generator analyzer

New Files:

• aspnet-openapi-xml-controllers/api/Api.csproj - Main API project file
• aspnet-openapi-xml-controllers/api/Api.http - 73 lines of example HTTP requests
• aspnet-openapi-xml-controllers/api/Controllers/ProjectBoardsController.cs - 119 lines
• aspnet-openapi-xml-controllers/api/Controllers/TodosController.cs - 161 lines
• aspnet-openapi-xml-controllers/api/Program.cs - Application startup configuration
• aspnet-openapi-xml-controllers/api/Properties/launchSettings.json - Launch profiles with Development environment
• aspnet-openapi-xml-controllers/api/appsettings.json & appsettings.Development.json - Configuration files
• aspnet-openapi-xml-controllers/api/AdditionalFiles.xml - External XML documentation example
• aspnet-openapi-xml-controllers/api/Api-remove.csproj.xml - Analyzer disable example
• aspnet-openapi-xml-controllers/models/Models.csproj - Shared models project
• aspnet-openapi-xml-controllers/models/ProjectBoard.cs - 32 lines
• aspnet-openapi-xml-controllers/models/Todo.cs - 47 lines
• aspnet-openapi-xml-controllers/models/TodoPriority.cs - 27 lines
• aspnet-openapi-xml-controllers/global.json - SDK version specification
• aspnet-openapi-xml/api/Properties/launchSettings.json - Launch profiles with Development environment

2. Bump OpenAPI Package Version

Updated Microsoft.AspNetCore.OpenApi package from preview version to stable 10.0.3 in the existing XML sample (aspnet-openapi-xml/api/Api.csproj).

Added #pragma warning disable ASPDEPR002 / #pragma warning restore ASPDEPR002 in aspnet-openapi-xml/api/ProjectBoardApis.cs to suppress deprecation warnings and maintain clean builds.

Modified Files:

• samples/10.x/aspnet-openapi-xml/api/Api.csproj - Package version update
• samples/10.x/aspnet-openapi-xml/api/ProjectBoardApis.cs - Added pragma directives
• Both API projects now include Properties/launchSettings.json with ASPNETCORE_ENVIRONMENT set to Development

3. Improve .gitignore for Rider IDE

Added .idea/ directory to .gitignore to exclude JetBrains Rider project files from version control, improving the development experience for contributors using Rider IDE.

Modified Files:

• .gitignore - Added Rider-specific ignore pattern

Testing

• ✅ All new sample code compiles successfully
• ✅ API endpoints functional with proper OpenAPI documentation
• ✅ Scalar UI displays XML documentation correctly
• ✅ HTTP requests in .http file validated
• ✅ External XML documentation integration working as expected

Additional Notes

• All changes target .NET 10
• Sample follows ASP.NET Core documentation standards
• Controller-based approach aligns with middleware class guidance in documentation
• XML documentation demonstrates best practices for API documentation

[max-lancaster]

@dotnet-policy-service agree