Update OData examples

Author: commonsensesoftware

examples/AspNetCore/OData/ODataOpenApiExample/ConfigureSwaggerOptions.cs

@@ -12,11 +12,15 @@
 public class FunctionsController : ODataController
 {
     /// <summary>
-    /// Gets the sales tax for a postal code.
+    /// Get Sales Tax
     /// </summary>
+    /// <description>Gets the sales tax for a postal code.</description>
     /// <param name="postalCode">The postal code to get the sales tax for.</param>
     /// <returns>The sales tax rate for the postal code.</returns>
+    /// <response code="200">The sales tax was successfully retrieved.</response>
+    /// <response code="404">The postal code was not found.</response>
     [HttpGet( "api/GetSalesTaxRate(PostalCode={postalCode})" )]
     [ProducesResponseType( typeof( double ), Status200OK )]
+    [ProducesResponseType( Status404NotFound )]
     public IActionResult GetSalesTaxRate( int postalCode ) => Ok( 5.6 );
 }

examples/AspNetCore/OData/ODataOpenApiExample/FunctionsController.cs

@@ -2,15 +2,22 @@
 
  <PropertyGroup>
   <TargetFramework>net10.0</TargetFramework>
+  <AssemblyTitle>Example API</AssemblyTitle>
   <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
 
  <ItemGroup>
-  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0-*" />
+  <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="10.0.*">
+   <PrivateAssets>all</PrivateAssets>
+   <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+  </PackageReference>
+  <PackageReference Include="Scalar.AspNetCore" Version="2.12.*" />
+  <PackageReference Include="Scalar.AspNetCore.Microsoft" Version="2.12.*" />
  </ItemGroup>
 
  <ItemGroup>
   <ProjectReference Include="..\..\..\..\src\AspNetCore\OData\src\Asp.Versioning.OData.ApiExplorer\Asp.Versioning.OData.ApiExplorer.csproj" />
+  <ProjectReference Include="..\..\..\..\src\AspNetCore\WebApi\src\Asp.Versioning.OpenApi\Asp.Versioning.OpenApi.csproj" />
  </ItemGroup>
 
 </Project>

examples/AspNetCore/OData/ODataOpenApiExample/ODataOpenApiExample.csproj

@@ -1,16 +1,17 @@
 using ApiVersioning.Examples;
 using Asp.Versioning;
 using Asp.Versioning.Conventions;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.AspNetCore.OData;
-using Microsoft.Extensions.Options;
-using Swashbuckle.AspNetCore.SwaggerGen;
+using Scalar.AspNetCore;
+using System.Reflection;
 using static Microsoft.AspNetCore.OData.Query.AllowedQueryOptions;
 using PeopleControllerV2 = ApiVersioning.Examples.V2.PeopleController;
 using PeopleControllerV3 = ApiVersioning.Examples.V3.PeopleController;
 
-var builder = WebApplication.CreateBuilder( args );
+[assembly: AssemblyDescription( "An example API" )]
 
-// Add services to the container.
+var builder = WebApplication.CreateBuilder( args );
 
 builder.Services.AddControllers()
                 .AddOData(
@@ -31,10 +32,16 @@
                         // "api-supported-versions" and "api-deprecated-versions"
                         options.ReportApiVersions = true;
 
+                        options.Policies.Deprecate( 0.9 )
+                                        .Effective( DateTimeOffset.Now )
+                                        .Link( "policy.html" )
+                                            .Title( "Version Deprecation Policy" )
+                                            .Type( "text/html" );
+
                         options.Policies.Sunset( 0.9 )
                                         .Effective( DateTimeOffset.Now.AddDays( 60 ) )
                                         .Link( "policy.html" )
-                                            .Title( "Versioning Policy" )
+                                            .Title( "Version Sunset Policy" )
                                             .Type( "text/html" );
                     } )
                 .AddOData( options => options.AddRouteComponents( "api" ) )
@@ -61,47 +68,27 @@
                                                 .Allow( Skip | Count )
                                                 .AllowTop( 100 )
                                                 .AllowOrderBy( "firstName", "lastName" );
-                    } );
-
-// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
-builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
-builder.Services.AddSwaggerGen(
-    options =>
-    {
-        // add a custom operation filter which sets default values
-        options.OperationFilter<SwaggerDefaultValues>();
-
-        var fileName = typeof( Program ).Assembly.GetName().Name + ".xml";
-        var filePath = Path.Combine( AppContext.BaseDirectory, fileName );
-
-        // integrate xml comments
-        options.IncludeXmlComments( filePath );
-    } );
+                    } )
+                .AddOpenApi( options => options.Document.AddScalarTransformers() );
 
 var app = builder.Build();
 
-// Configure HTTP request pipeline.
-
 if ( app.Environment.IsDevelopment() )
 {
-    // Access ~/$odata to identify OData endpoints that failed to match a route template.
+    // access ~/$odata to identify OData endpoints that failed to match a route template
     app.UseODataRouteDebug();
-}
-
-app.UseSwagger();
-if ( app.Environment.IsDevelopment() )
-{
-    app.UseSwaggerUI(
+    app.MapOpenApi().WithDocumentPerVersion();
+    app.MapScalarApiReference(
         options =>
         {
             var descriptions = app.DescribeApiVersions();
 
-            // build a swagger endpoint for each discovered API version
-            foreach ( var description in descriptions )
+            for ( var i = 0; i < descriptions.Count; i++ )
             {
-                var url = $"/swagger/{description.GroupName}/swagger.json";
-                var name = description.GroupName.ToUpperInvariant();
-                options.SwaggerEndpoint( url, name );
+                var description = descriptions[i];
+                var isDefault = i == descriptions.Count - 1;
+
+                options.AddDocument( description.GroupName, description.GroupName, isDefault: isDefault );
             }
         } );
 }

examples/AspNetCore/OData/ODataOpenApiExample/Program.cs

@@ -12,7 +12,7 @@
       "commandName": "Project",
       "dotnetRunMessages": true,
       "launchBrowser": true,
-      "launchUrl": "swagger",
+      "launchUrl": "scalar",
       "applicationUrl": "https://localhost:5001;http://localhost:5000",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
@@ -21,7 +21,7 @@
     "IIS Express": {
       "commandName": "IISExpress",
       "launchBrowser": true,
-      "launchUrl": "swagger",
+      "launchUrl": "scalar",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       }