diff --git a/asp.slnx b/asp.slnx index ba9a40e3..361eb66d 100644 --- a/asp.slnx +++ b/asp.slnx @@ -49,6 +49,7 @@ + @@ -69,7 +70,6 @@ - diff --git a/examples/AspNet/Directory.Build.props b/examples/AspNet/Directory.Build.props index 7b79f5c1..270ea322 100644 --- a/examples/AspNet/Directory.Build.props +++ b/examples/AspNet/Directory.Build.props @@ -2,21 +2,6 @@ - - - Exe - - - - - - - - - <_Parameter1>ApiVersioning.Examples.Startup - <_Parameter1_TypeName>System.Type - - diff --git a/examples/AspNet/OData/AdvancedODataWebApiExample/AdvancedODataWebApiExample.csproj b/examples/AspNet/OData/AdvancedODataWebApiExample/AdvancedODataWebApiExample.csproj index f1e7436f..8f72accd 100644 --- a/examples/AspNet/OData/AdvancedODataWebApiExample/AdvancedODataWebApiExample.csproj +++ b/examples/AspNet/OData/AdvancedODataWebApiExample/AdvancedODataWebApiExample.csproj @@ -2,12 +2,17 @@ net48 + Exe + + + + diff --git a/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/OrderModelConfiguration.cs b/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/OrderModelConfiguration.cs index 6c8f249f..6aca4f5d 100644 --- a/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/OrderModelConfiguration.cs +++ b/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/OrderModelConfiguration.cs @@ -13,7 +13,7 @@ private EntityTypeConfiguration ConfigureCurrent( ODataModelBuilder build { var order = builder.EntitySet( "Orders" ).EntityType; - order.HasKey( p => p.Id ); + order.HasKey( p => p.Id ).Select(); return order; } diff --git a/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/PersonModelConfiguration.cs b/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/PersonModelConfiguration.cs index 35cca223..66f21774 100644 --- a/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/PersonModelConfiguration.cs +++ b/examples/AspNet/OData/AdvancedODataWebApiExample/Configuration/PersonModelConfiguration.cs @@ -20,7 +20,7 @@ private EntityTypeConfiguration ConfigureCurrent( ODataModelBuilder buil { var person = builder.EntitySet( "People" ).EntityType; - person.HasKey( p => p.Id ); + person.HasKey( p => p.Id ).Select(); return person; } diff --git a/examples/AspNet/OData/AdvancedODataWebApiExample/Examples.http b/examples/AspNet/OData/AdvancedODataWebApiExample/Examples.http new file mode 100644 index 00000000..57aea639 --- /dev/null +++ b/examples/AspNet/OData/AdvancedODataWebApiExample/Examples.http @@ -0,0 +1,74 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:9006 + +### VERSION 1.0 + +### People - Get All (OData) +# Note: assumes the version when AssumeDefaultVersionWhenUnspecified = true, +# which is meant for existing, unversioned apis +GET {{baseUrl}}/api/people + +### People - Get All (OData) +GET {{baseUrl}}/api/people?api-version=1.0 + +### People - Get All with $select (OData) +GET {{baseUrl}}/api/people?api-version=1.0&$select=firstName,lastName + +### People - Get by Key (OData) +GET {{baseUrl}}/api/people/1?api-version=1.0 + +### Orders - Get All (Standard) +# Note: assumes the version when AssumeDefaultVersionWhenUnspecified = true, +# which is meant for existing, unversioned apis +GET {{baseUrl}}/api/orders + +### Orders - Get All (Standard) +GET {{baseUrl}}/api/orders?api-version=1.0 + +### Orders - Get by Key (Standard) +GET {{baseUrl}}/api/orders/1?api-version=1.0 + +### VERSION 2.0 + +### People - Get All (OData) +GET {{baseUrl}}/api/people?api-version=2.0 + +### People - Get All with $select (OData) +GET {{baseUrl}}/api/people?api-version=2.0&$select=firstName,lastName,email + +### People - Get by Key (OData) +GET {{baseUrl}}/api/people/1?api-version=2.0 + +### People - Partial Update (OData) +PATCH {{baseUrl}}/api/people/1?api-version=2.0 +content-type: application/json +prefer: return=representation + +{"firstName":"John","lastName":"Doe"} + +### Orders - Get All (OData) +GET {{baseUrl}}/api/orders?api-version=2.0 + +### Orders - Get All with $select (OData) +GET {{baseUrl}}/api/orders?api-version=2.0&$select=id,customer + +### Orders - Get by Key (OData) +GET {{baseUrl}}/api/orders/1?api-version=2.0 + +### VERSION 3.0 + +### People - Get All (OData) +GET {{baseUrl}}/api/people?api-version=3.0 + +### People - Get All with $select (OData) +GET {{baseUrl}}/api/people?api-version=3.0&$select=firstName,lastName,email + +### People - Get by Key (OData) +GET {{baseUrl}}/api/people/1?api-version=3.0 + +### Orders - Get All (Standard) +GET {{baseUrl}}/api/orders?api-version=3.0 + +### Orders - Get by Key (Standard) +GET {{baseUrl}}/api/orders/1?api-version=3.0 \ No newline at end of file diff --git a/examples/AspNet/OData/AdvancedODataWebApiExample/README.md b/examples/AspNet/OData/AdvancedODataWebApiExample/README.md new file mode 100644 index 00000000..8a3708fd --- /dev/null +++ b/examples/AspNet/OData/AdvancedODataWebApiExample/README.md @@ -0,0 +1,5 @@ +# ASP.NET Web API with OData Advanced Example + +This example project illustrates advanced scenarios that mixes and matches between standard ASP.NET Web API controllers +and OData controllers. Services can transition to or from OData across API versions. Launch the project and try the +[example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNet/OData/BasicODataWebApiExample/BasicODataWebApiExample.csproj b/examples/AspNet/OData/BasicODataWebApiExample/BasicODataWebApiExample.csproj index f1e7436f..8f72accd 100644 --- a/examples/AspNet/OData/BasicODataWebApiExample/BasicODataWebApiExample.csproj +++ b/examples/AspNet/OData/BasicODataWebApiExample/BasicODataWebApiExample.csproj @@ -2,12 +2,17 @@ net48 + Exe + + + + diff --git a/examples/AspNet/OData/BasicODataWebApiExample/Configuration/OrderModelConfiguration.cs b/examples/AspNet/OData/BasicODataWebApiExample/Configuration/OrderModelConfiguration.cs index 88ce68c3..df15b2f4 100644 --- a/examples/AspNet/OData/BasicODataWebApiExample/Configuration/OrderModelConfiguration.cs +++ b/examples/AspNet/OData/BasicODataWebApiExample/Configuration/OrderModelConfiguration.cs @@ -13,7 +13,7 @@ private EntityTypeConfiguration ConfigureCurrent( ODataModelBuilder build { var order = builder.EntitySet( "Orders" ).EntityType; - order.HasKey( p => p.Id ); + order.HasKey( p => p.Id ).Select(); return order; } diff --git a/examples/AspNet/OData/BasicODataWebApiExample/Configuration/PersonModelConfiguration.cs b/examples/AspNet/OData/BasicODataWebApiExample/Configuration/PersonModelConfiguration.cs index 289045f4..0ba7c9c5 100644 --- a/examples/AspNet/OData/BasicODataWebApiExample/Configuration/PersonModelConfiguration.cs +++ b/examples/AspNet/OData/BasicODataWebApiExample/Configuration/PersonModelConfiguration.cs @@ -20,7 +20,7 @@ private EntityTypeConfiguration ConfigureCurrent( ODataModelBuilder buil { var person = builder.EntitySet( "People" ).EntityType; - person.HasKey( p => p.Id ); + person.HasKey( p => p.Id ).Select(); return person; } diff --git a/examples/AspNet/OData/BasicODataWebApiExample/Examples.http b/examples/AspNet/OData/BasicODataWebApiExample/Examples.http new file mode 100644 index 00000000..16a18f98 --- /dev/null +++ b/examples/AspNet/OData/BasicODataWebApiExample/Examples.http @@ -0,0 +1,55 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:9004 + +### ------------------------------ BY QUERY STRING ------------------------------ + +### VERSION 1.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=1.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=1.0&$select=firstName,lastName + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=1.0 + +### VERSION 2.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=2.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=2.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=2.0 + +### People - Partial Update +PATCH {{baseUrl}}/api/people/1?api-version=2.0 +content-type: application/json +prefer: return=representation + +{"firstName":"John","lastName":"Doe"} + +### VERSION 3.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=3.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=3.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=3.0 + +### ------------------------------ BY URL SEGMENT ------------------------------ + +### VERSION 1.0 + +### Orders - Get All +GET {{baseUrl}}/api/v1/orders + +### Orders - Get by Key +GET {{baseUrl}}/api/v1/orders/1 \ No newline at end of file diff --git a/examples/AspNet/OData/BasicODataWebApiExample/README.md b/examples/AspNet/OData/BasicODataWebApiExample/README.md new file mode 100644 index 00000000..4bddbbf8 --- /dev/null +++ b/examples/AspNet/OData/BasicODataWebApiExample/README.md @@ -0,0 +1,4 @@ +# ASP.NET Web API with OData Basic Example + +This example project illustrates a bare bones, basic setup using OData endpoints. Launch the project and try the +[example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/OrderModelConfiguration.cs b/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/OrderModelConfiguration.cs index 88ce68c3..df15b2f4 100644 --- a/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/OrderModelConfiguration.cs +++ b/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/OrderModelConfiguration.cs @@ -13,7 +13,7 @@ private EntityTypeConfiguration ConfigureCurrent( ODataModelBuilder build { var order = builder.EntitySet( "Orders" ).EntityType; - order.HasKey( p => p.Id ); + order.HasKey( p => p.Id ).Select(); return order; } diff --git a/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/PersonModelConfiguration.cs b/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/PersonModelConfiguration.cs index 289045f4..0ba7c9c5 100644 --- a/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/PersonModelConfiguration.cs +++ b/examples/AspNet/OData/ConventionsODataWebApiExample/Configuration/PersonModelConfiguration.cs @@ -20,7 +20,7 @@ private EntityTypeConfiguration ConfigureCurrent( ODataModelBuilder buil { var person = builder.EntitySet( "People" ).EntityType; - person.HasKey( p => p.Id ); + person.HasKey( p => p.Id ).Select(); return person; } diff --git a/examples/AspNet/OData/ConventionsODataWebApiExample/ConventionsODataWebApiExample.csproj b/examples/AspNet/OData/ConventionsODataWebApiExample/ConventionsODataWebApiExample.csproj index f1e7436f..8f72accd 100644 --- a/examples/AspNet/OData/ConventionsODataWebApiExample/ConventionsODataWebApiExample.csproj +++ b/examples/AspNet/OData/ConventionsODataWebApiExample/ConventionsODataWebApiExample.csproj @@ -2,12 +2,17 @@ net48 + Exe + + + + diff --git a/examples/AspNet/OData/ConventionsODataWebApiExample/Examples.http b/examples/AspNet/OData/ConventionsODataWebApiExample/Examples.http new file mode 100644 index 00000000..63ea1849 --- /dev/null +++ b/examples/AspNet/OData/ConventionsODataWebApiExample/Examples.http @@ -0,0 +1,55 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:9005 + +### ------------------------------ BY QUERY STRING ------------------------------ + +### VERSION 1.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=1.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=1.0&$select=firstName,lastName + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=1.0 + +### VERSION 2.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=2.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=2.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=2.0 + +### People - Partial Update +PATCH {{baseUrl}}/api/people/1?api-version=2.0 +content-type: application/json +prefer: return=representation + +{"firstName":"John","lastName":"Doe"} + +### VERSION 3.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=3.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=3.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=3.0 + +### ------------------------------ BY URL SEGMENT ------------------------------ + +### VERSION 1.0 + +### Orders - Get All +GET {{baseUrl}}/api/v1/orders + +### Orders - Get by Key +GET {{baseUrl}}/api/v1/orders/1 \ No newline at end of file diff --git a/examples/AspNet/OData/ConventionsODataWebApiExample/README.md b/examples/AspNet/OData/ConventionsODataWebApiExample/README.md new file mode 100644 index 00000000..0003a49a --- /dev/null +++ b/examples/AspNet/OData/ConventionsODataWebApiExample/README.md @@ -0,0 +1,6 @@ +# ASP.NET Web API with OData Conventions Example + +This example project illustrates using ASP.NET Core with OData by applying API version metadata with conventions +instead of attributes. This approach is useful if you prefer not to decorate controllers with API versions or in a +scenario where you might not have the ability to apply attributes yourself, such as in a plug-in model. Launch the +project and try the [example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNet/OData/OpenApiODataWebApiExample/OpenApiODataWebApiExample.csproj b/examples/AspNet/OData/OpenApiODataWebApiExample/OpenApiODataWebApiExample.csproj index 19a3f346..e460442a 100644 --- a/examples/AspNet/OData/OpenApiODataWebApiExample/OpenApiODataWebApiExample.csproj +++ b/examples/AspNet/OData/OpenApiODataWebApiExample/OpenApiODataWebApiExample.csproj @@ -2,6 +2,7 @@ net48 + Exe bin\$(Configuration)\$(TargetFramework)\$(MSBuildThisFileName).xml @@ -10,7 +11,8 @@ - + + diff --git a/examples/AspNet/OData/OpenApiODataWebApiExample/README.md b/examples/AspNet/OData/OpenApiODataWebApiExample/README.md new file mode 100644 index 00000000..e54ac4a9 --- /dev/null +++ b/examples/AspNet/OData/OpenApiODataWebApiExample/README.md @@ -0,0 +1,7 @@ +# ASP.NET Web API OData OpenAPI Example + +This example project illustrates using OData endpoints with [OpenAPI] and [Swashbuckle]. Launch the project and try the +example requests to view an API in action. + +[OpenAPI]: https://www.openapis.org/ +[Swashbuckle]: https://github.com/domaindrivendev/Swashbuckle.WebApi \ No newline at end of file diff --git a/examples/AspNet/OData/SomeOpenApiODataWebApiExample/README.md b/examples/AspNet/OData/SomeOpenApiODataWebApiExample/README.md new file mode 100644 index 00000000..53db1085 --- /dev/null +++ b/examples/AspNet/OData/SomeOpenApiODataWebApiExample/README.md @@ -0,0 +1,8 @@ +# ASP.NET Web API with Some OData OpenAPI Example + +This example project illustrates using standard ASP.NET Core controllers and OData query capabilities without fully +adhering to the OData protocol while also integrating with [OpenAPI] and [Swashbuckle]. Launch the project and try the +example requests to view an API in action. + +[OpenAPI]: https://www.openapis.org/ +[Swashbuckle]: https://github.com/domaindrivendev/Swashbuckle.WebApi \ No newline at end of file diff --git a/examples/AspNet/OData/SomeOpenApiODataWebApiExample/SomeOpenApiODataWebApiExample.csproj b/examples/AspNet/OData/SomeOpenApiODataWebApiExample/SomeOpenApiODataWebApiExample.csproj index 19a3f346..dd6d3345 100644 --- a/examples/AspNet/OData/SomeOpenApiODataWebApiExample/SomeOpenApiODataWebApiExample.csproj +++ b/examples/AspNet/OData/SomeOpenApiODataWebApiExample/SomeOpenApiODataWebApiExample.csproj @@ -2,6 +2,7 @@ net48 +Exe bin\$(Configuration)\$(TargetFramework)\$(MSBuildThisFileName).xml @@ -10,7 +11,8 @@ - + + diff --git a/examples/AspNet/WebApi/BasicWebApiExample/BasicWebApiExample.csproj b/examples/AspNet/WebApi/BasicWebApiExample/BasicWebApiExample.csproj index 65c3521c..1550d248 100644 --- a/examples/AspNet/WebApi/BasicWebApiExample/BasicWebApiExample.csproj +++ b/examples/AspNet/WebApi/BasicWebApiExample/BasicWebApiExample.csproj @@ -2,8 +2,13 @@ net48 + Exe + + + + diff --git a/examples/AspNet/WebApi/BasicWebApiExample/Controllers/MultiVersionedController.cs b/examples/AspNet/WebApi/BasicWebApiExample/Controllers/MultiVersionedController.cs new file mode 100644 index 00000000..96f00a36 --- /dev/null +++ b/examples/AspNet/WebApi/BasicWebApiExample/Controllers/MultiVersionedController.cs @@ -0,0 +1,16 @@ +namespace ApiVersioning.Examples.Controllers; + +using Asp.Versioning; +using System.Web.Http; + +[ApiVersion( 1.0 )] +[ApiVersion( 2.0 )] +[Route( "api/v{version:apiVersion}/multiversioned" )] +public class MultiVersionedController : ApiController +{ + [HttpGet] + public string Get( ApiVersion version ) => "Version " + version; + + [HttpGet, MapToApiVersion( 2.0 )] + public string GetV2( ApiVersion version ) => "Version " + version; +} \ No newline at end of file diff --git a/examples/AspNet/WebApi/BasicWebApiExample/Examples.http b/examples/AspNet/WebApi/BasicWebApiExample/Examples.http new file mode 100644 index 00000000..4b8d77b1 --- /dev/null +++ b/examples/AspNet/WebApi/BasicWebApiExample/Examples.http @@ -0,0 +1,30 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:9000 + +### VERSION 1.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=1.0 + +### Hello World - Get +GET {{baseUrl}}/api/v1/helloworld + +### Hello World - Get by ID +GET {{baseUrl}}/api/v1/helloworld/42 + +### Hello World - Create +POST {{baseUrl}}/api/v1/helloworld + +### Multi-Versioned - Get +# note: this controller has a single, version interleaved implementation +GET {{baseUrl}}/api/v1/multiversioned + +### VERSION 2.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=2.0 + +### Multi-Versioned - Get +# note: this controller has a single, version interleaved implementation +GET {{baseUrl}}/api/v2/multiversioned \ No newline at end of file diff --git a/examples/AspNet/WebApi/BasicWebApiExample/Program.cs b/examples/AspNet/WebApi/BasicWebApiExample/Program.cs index 36a2ee76..92b1f068 100644 --- a/examples/AspNet/WebApi/BasicWebApiExample/Program.cs +++ b/examples/AspNet/WebApi/BasicWebApiExample/Program.cs @@ -1,4 +1,6 @@ -namespace ApiVersioning.Examples; +[assembly: Microsoft.Owin.OwinStartup( typeof( ApiVersioning.Examples.Startup ) )] + +namespace ApiVersioning.Examples; using Microsoft.Owin.Hosting; diff --git a/examples/AspNet/WebApi/BasicWebApiExample/README.md b/examples/AspNet/WebApi/BasicWebApiExample/README.md new file mode 100644 index 00000000..2b73ce2d --- /dev/null +++ b/examples/AspNet/WebApi/BasicWebApiExample/README.md @@ -0,0 +1,4 @@ +# ASP.NET Web API Basic Example + +This example project illustrates a bare bones, basic setup using standard ASP.NET Web API controllers. Launch the +project and try the [example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNet/WebApi/ByNamespaceWebApiExample/ByNamespaceWebApiExample.csproj b/examples/AspNet/WebApi/ByNamespaceWebApiExample/ByNamespaceWebApiExample.csproj index 65c3521c..1550d248 100644 --- a/examples/AspNet/WebApi/ByNamespaceWebApiExample/ByNamespaceWebApiExample.csproj +++ b/examples/AspNet/WebApi/ByNamespaceWebApiExample/ByNamespaceWebApiExample.csproj @@ -2,8 +2,13 @@ net48 + Exe + + + + diff --git a/examples/AspNet/WebApi/ByNamespaceWebApiExample/Examples.http b/examples/AspNet/WebApi/ByNamespaceWebApiExample/Examples.http new file mode 100644 index 00000000..4ff5f988 --- /dev/null +++ b/examples/AspNet/WebApi/ByNamespaceWebApiExample/Examples.http @@ -0,0 +1,55 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:9002 + +### ------------------------------ BY QUERY STRING ------------------------------ + +### VERSION 1.0 + +### Agreements - Get by ID +GET {{baseUrl}}/agreements/42?api-version=1.0 + +### Orders - Get by ID +GET {{baseUrl}}/orders/42?api-version=1.0 + +### VERSION 2.0 + +### Agreements - Get by ID +GET {{baseUrl}}/agreements/42?api-version=2.0 + +### Orders - Get by ID +GET {{baseUrl}}/orders/42?api-version=2.0 + +### VERSION 3.0 + +### Agreements - Get by ID +GET {{baseUrl}}/agreements/42?api-version=3.0 + +### Orders - Get by ID +GET {{baseUrl}}/orders/42?api-version=3.0 + +### ------------------------------ BY URL SEGMENT ------------------------------ + +### VERSION 1.0 + +### Agreements - Get by ID +GET {{baseUrl}}/v1/agreements/42 + +### Orders - Get by ID +GET {{baseUrl}}/v1/orders/42 + +### VERSION 2.0 + +### Agreements - Get by ID +GET {{baseUrl}}/v2/agreements/42 + +### Orders - Get by ID +GET {{baseUrl}}/v2/orders/42 + +### VERSION 3.0 + +### Agreements - Get by ID +GET {{baseUrl}}/v3/agreements/42 + +### Orders - Get by ID +GET {{baseUrl}}/v3/orders/42 \ No newline at end of file diff --git a/examples/AspNet/WebApi/ByNamespaceWebApiExample/Program.cs b/examples/AspNet/WebApi/ByNamespaceWebApiExample/Program.cs index 7e241aec..8da3eecf 100644 --- a/examples/AspNet/WebApi/ByNamespaceWebApiExample/Program.cs +++ b/examples/AspNet/WebApi/ByNamespaceWebApiExample/Program.cs @@ -1,4 +1,6 @@ -namespace ApiVersioning.Examples; +[assembly: Microsoft.Owin.OwinStartup( typeof( ApiVersioning.Examples.Startup ) )] + +namespace ApiVersioning.Examples; using Microsoft.Owin.Hosting; diff --git a/examples/AspNet/WebApi/ByNamespaceWebApiExample/README.md b/examples/AspNet/WebApi/ByNamespaceWebApiExample/README.md new file mode 100644 index 00000000..c312f216 --- /dev/null +++ b/examples/AspNet/WebApi/ByNamespaceWebApiExample/README.md @@ -0,0 +1,9 @@ +# ASP.NET Web API Version By Namespace Convention Example + +This example project illustrates using ASP.NET Web API controllers which have their API version applied using the +[version by .NET namespace convention][wiki] instead of attributes. This approach is useful if you prefer not to +decorate controllers with API versions and have them automatically versioned using the .NET namespace that defines +their type. Launch the project and try the [example requests](Examples.http) to view an API in action. + + +[wiki]: https://github.com/dotnet/aspnet-api-versioning/wiki/API-Version-Conventions#version-by-namespace-convention \ No newline at end of file diff --git a/examples/AspNet/WebApi/ByNamespaceWebApiExample/Startup.cs b/examples/AspNet/WebApi/ByNamespaceWebApiExample/Startup.cs index 6775b288..2b8e1b04 100644 --- a/examples/AspNet/WebApi/ByNamespaceWebApiExample/Startup.cs +++ b/examples/AspNet/WebApi/ByNamespaceWebApiExample/Startup.cs @@ -29,7 +29,7 @@ public void Configuration( IAppBuilder builder ) // experiment with either configuration. one of these would be removed in a real application. configuration.Routes.MapHttpRoute( "VersionedQueryString", - "api/{controller}/{accountId}", + "{controller}/{accountId}", defaults: null ); configuration.Routes.MapHttpRoute( diff --git a/examples/AspNet/WebApi/ConventionsWebApiExample/ConventionsWebApiExample.csproj b/examples/AspNet/WebApi/ConventionsWebApiExample/ConventionsWebApiExample.csproj index 65c3521c..1550d248 100644 --- a/examples/AspNet/WebApi/ConventionsWebApiExample/ConventionsWebApiExample.csproj +++ b/examples/AspNet/WebApi/ConventionsWebApiExample/ConventionsWebApiExample.csproj @@ -2,8 +2,13 @@ net48 + Exe + + + + diff --git a/examples/AspNet/WebApi/ConventionsWebApiExample/Examples.http b/examples/AspNet/WebApi/ConventionsWebApiExample/Examples.http new file mode 100644 index 00000000..7badf6ca --- /dev/null +++ b/examples/AspNet/WebApi/ConventionsWebApiExample/Examples.http @@ -0,0 +1,30 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:9001 + +### VERSION 1.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=1.0 + +### Hello World - Get +GET {{baseUrl}}/api/v1/helloworld + +### Hello World - Get by ID +GET {{baseUrl}}/api/v1/helloworld/42 + +### VERSION 2.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=2.0 + +### Hello World - Get +GET {{baseUrl}}/api/v2/helloworld + +### Hello World - Get by ID +GET {{baseUrl}}/api/v2/helloworld/42 + +### VERSION 3.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=3.0 \ No newline at end of file diff --git a/examples/AspNet/WebApi/ConventionsWebApiExample/Program.cs b/examples/AspNet/WebApi/ConventionsWebApiExample/Program.cs index 712cd6c8..4c5b411a 100644 --- a/examples/AspNet/WebApi/ConventionsWebApiExample/Program.cs +++ b/examples/AspNet/WebApi/ConventionsWebApiExample/Program.cs @@ -1,4 +1,6 @@ -namespace ApiVersioning.Examples; +[assembly: Microsoft.Owin.OwinStartup( typeof( ApiVersioning.Examples.Startup ) )] + +namespace ApiVersioning.Examples; using Microsoft.Owin.Hosting; diff --git a/examples/AspNet/WebApi/ConventionsWebApiExample/README.md b/examples/AspNet/WebApi/ConventionsWebApiExample/README.md new file mode 100644 index 00000000..ebe80889 --- /dev/null +++ b/examples/AspNet/WebApi/ConventionsWebApiExample/README.md @@ -0,0 +1,6 @@ +# ASP.NET Web API Conventions Example + +This example project illustrates using ASP.NET Web API controllers by applying API version metadata with conventions +instead of attributes. This approach is useful if you prefer not to decorate controllers with API versions or in a +scenario where you might not have the ability to apply attributes yourself, such as in a plug-in model. Launch the +project and try the [example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNet/WebApi/OpenApiWebApiExample/OpenApiWebApiExample.csproj b/examples/AspNet/WebApi/OpenApiWebApiExample/OpenApiWebApiExample.csproj index 4d21c14d..6e29df34 100644 --- a/examples/AspNet/WebApi/OpenApiWebApiExample/OpenApiWebApiExample.csproj +++ b/examples/AspNet/WebApi/OpenApiWebApiExample/OpenApiWebApiExample.csproj @@ -2,6 +2,7 @@ net48 + Exe bin\$(Configuration)\$(TargetFramework)\$(MSBuildThisFileName).xml @@ -10,11 +11,12 @@ - + + - + \ No newline at end of file diff --git a/examples/AspNet/WebApi/OpenApiWebApiExample/Program.cs b/examples/AspNet/WebApi/OpenApiWebApiExample/Program.cs index 89a4da2d..ae9e7545 100644 --- a/examples/AspNet/WebApi/OpenApiWebApiExample/Program.cs +++ b/examples/AspNet/WebApi/OpenApiWebApiExample/Program.cs @@ -1,8 +1,11 @@ -namespace ApiVersioning.Examples; +[assembly: Microsoft.Owin.OwinStartup( typeof( ApiVersioning.Examples.Startup ) )] + +namespace ApiVersioning.Examples; using Microsoft.Owin.Hosting; using System.Diagnostics; + /// /// Represents the current application. /// diff --git a/examples/AspNet/WebApi/OpenApiWebApiExample/README.md b/examples/AspNet/WebApi/OpenApiWebApiExample/README.md new file mode 100644 index 00000000..0026d225 --- /dev/null +++ b/examples/AspNet/WebApi/OpenApiWebApiExample/README.md @@ -0,0 +1,7 @@ +# ASP.NET Web API OpenAPI Example + +This example project illustrates using standard ASP.NET Core controllers with [OpenAPI] and [Swashbuckle]. Launch the +project and try the example requests to view an API in action. + +[OpenAPI]: https://www.openapis.org/ +[Swashbuckle]: https://github.com/domaindrivendev/Swashbuckle.WebApi \ No newline at end of file diff --git a/examples/AspNetCore/Directory.Build.props b/examples/AspNetCore/Directory.Build.props deleted file mode 100644 index 28e9057c..00000000 --- a/examples/AspNetCore/Directory.Build.props +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - net8.0 - - - \ No newline at end of file diff --git a/examples/AspNetCore/OData/Directory.Build.props b/examples/AspNetCore/OData/Directory.Build.props deleted file mode 100644 index d75382b4..00000000 --- a/examples/AspNetCore/OData/Directory.Build.props +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - \ No newline at end of file diff --git a/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/OrderModelConfiguration.cs b/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/OrderModelConfiguration.cs index b0a79db7..f807bb75 100644 --- a/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/OrderModelConfiguration.cs +++ b/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/OrderModelConfiguration.cs @@ -13,7 +13,7 @@ private static EntityTypeConfiguration ConfigureCurrent( ODataModelBuilde { var order = builder.EntitySet( "Orders" ).EntityType; - order.HasKey( p => p.Id ); + order.HasKey( p => p.Id ).Select(); return order; } diff --git a/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/PersonModelConfiguration.cs b/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/PersonModelConfiguration.cs index f462cb9a..b881c95a 100644 --- a/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/PersonModelConfiguration.cs +++ b/examples/AspNetCore/OData/ODataAdvancedExample/Configuration/PersonModelConfiguration.cs @@ -20,7 +20,7 @@ private static EntityTypeConfiguration ConfigureCurrent( ODataModelBuild { var person = builder.EntitySet( "People" ).EntityType; - person.HasKey( p => p.Id ); + person.HasKey( p => p.Id ).Select(); return person; } diff --git a/examples/AspNetCore/OData/ODataAdvancedExample/Controllers/PeopleController.cs b/examples/AspNetCore/OData/ODataAdvancedExample/Controllers/PeopleController.cs index 206a587c..689da5b9 100644 --- a/examples/AspNetCore/OData/ODataAdvancedExample/Controllers/PeopleController.cs +++ b/examples/AspNetCore/OData/ODataAdvancedExample/Controllers/PeopleController.cs @@ -47,7 +47,9 @@ public IActionResult Get( int key, ODataQueryOptions options, ApiVersion public IActionResult Patch( int key, Delta delta, ODataQueryOptions options, ApiVersion version ) { if ( !ModelState.IsValid ) + { return BadRequest( ModelState ); + } var person = new Person() { diff --git a/examples/AspNetCore/OData/ODataAdvancedExample/Examples.http b/examples/AspNetCore/OData/ODataAdvancedExample/Examples.http new file mode 100644 index 00000000..e6108122 --- /dev/null +++ b/examples/AspNetCore/OData/ODataAdvancedExample/Examples.http @@ -0,0 +1,74 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:5000 + +### VERSION 1.0 + +### People - Get All (OData) +# Note: assumes the version when AssumeDefaultVersionWhenUnspecified = true, +# which is meant for existing, unversioned apis +GET {{baseUrl}}/api/people + +### People - Get All (OData) +GET {{baseUrl}}/api/people?api-version=1.0 + +### People - Get All with $select (OData) +GET {{baseUrl}}/api/people?api-version=1.0&$select=firstName,lastName + +### People - Get by Key (OData) +GET {{baseUrl}}/api/people/1?api-version=1.0 + +### Orders - Get All (Standard) +# Note: assumes the version when AssumeDefaultVersionWhenUnspecified = true, +# which is meant for existing, unversioned apis +GET {{baseUrl}}/api/orders + +### Orders - Get All (Standard) +GET {{baseUrl}}/api/orders?api-version=1.0 + +### Orders - Get by Key (Standard) +GET {{baseUrl}}/api/orders/1?api-version=1.0 + +### VERSION 2.0 + +### People - Get All (OData) +GET {{baseUrl}}/api/people?api-version=2.0 + +### People - Get All with $select (OData) +GET {{baseUrl}}/api/people?api-version=2.0&$select=firstName,lastName,email + +### People - Get by Key (OData) +GET {{baseUrl}}/api/people/1?api-version=2.0 + +### People - Partial Update (OData) +PATCH {{baseUrl}}/api/people/1?api-version=2.0 +content-type: application/json +prefer: return=representation + +{"firstName":"John","lastName":"Doe"} + +### Orders - Get All (OData) +GET {{baseUrl}}/api/orders?api-version=2.0 + +### Orders - Get All with $select (OData) +GET {{baseUrl}}/api/orders?api-version=2.0&$select=id,customer + +### Orders - Get by Key (OData) +GET {{baseUrl}}/api/orders/1?api-version=2.0 + +### VERSION 3.0 + +### People - Get All (OData) +GET {{baseUrl}}/api/people?api-version=3.0 + +### People - Get All with $select (OData) +GET {{baseUrl}}/api/people?api-version=3.0&$select=firstName,lastName,email + +### People - Get by Key (OData) +GET {{baseUrl}}/api/people/1?api-version=3.0 + +### Orders - Get All (Standard) +GET {{baseUrl}}/api/orders?api-version=3.0 + +### Orders - Get by Key (Standard) +GET {{baseUrl}}/api/orders/1?api-version=3.0 \ No newline at end of file diff --git a/examples/AspNetCore/OData/ODataAdvancedExample/ODataAdvancedExample.csproj b/examples/AspNetCore/OData/ODataAdvancedExample/ODataAdvancedExample.csproj index 45e10dc9..ed77dfd1 100644 --- a/examples/AspNetCore/OData/ODataAdvancedExample/ODataAdvancedExample.csproj +++ b/examples/AspNetCore/OData/ODataAdvancedExample/ODataAdvancedExample.csproj @@ -4,6 +4,10 @@ net10.0 + + + + diff --git a/examples/AspNetCore/OData/ODataAdvancedExample/README.md b/examples/AspNetCore/OData/ODataAdvancedExample/README.md new file mode 100644 index 00000000..55c52b93 --- /dev/null +++ b/examples/AspNetCore/OData/ODataAdvancedExample/README.md @@ -0,0 +1,5 @@ +# ASP.NET Core with OData Advanced Example + +This example project illustrates advanced scenarios that mixes and matches between standard ASP.NET Core endpoints and +OData endpoints. Services can transition to or from OData across API versions. Launch the project and try the +[example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNetCore/OData/ODataBasicExample/Configuration/OrderModelConfiguration.cs b/examples/AspNetCore/OData/ODataBasicExample/Configuration/OrderModelConfiguration.cs index c757921a..b6d9388b 100644 --- a/examples/AspNetCore/OData/ODataBasicExample/Configuration/OrderModelConfiguration.cs +++ b/examples/AspNetCore/OData/ODataBasicExample/Configuration/OrderModelConfiguration.cs @@ -13,7 +13,7 @@ private static EntityTypeConfiguration ConfigureCurrent( ODataModelBuilde { var order = builder.EntitySet( "Orders" ).EntityType; - order.HasKey( p => p.Id ); + order.HasKey( p => p.Id ).Select(); return order; } diff --git a/examples/AspNetCore/OData/ODataBasicExample/Configuration/PersonModelConfiguration.cs b/examples/AspNetCore/OData/ODataBasicExample/Configuration/PersonModelConfiguration.cs index 5ebaa0db..89958bd4 100644 --- a/examples/AspNetCore/OData/ODataBasicExample/Configuration/PersonModelConfiguration.cs +++ b/examples/AspNetCore/OData/ODataBasicExample/Configuration/PersonModelConfiguration.cs @@ -20,7 +20,7 @@ private static EntityTypeConfiguration ConfigureCurrent( ODataModelBuild { var person = builder.EntitySet( "People" ).EntityType; - person.HasKey( p => p.Id ); + person.HasKey( p => p.Id ).Select(); return person; } diff --git a/examples/AspNetCore/OData/ODataBasicExample/Examples.http b/examples/AspNetCore/OData/ODataBasicExample/Examples.http new file mode 100644 index 00000000..55e26437 --- /dev/null +++ b/examples/AspNetCore/OData/ODataBasicExample/Examples.http @@ -0,0 +1,55 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:5000 + +### ------------------------------ BY QUERY STRING ------------------------------ + +### VERSION 1.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=1.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=1.0&$select=firstName,lastName + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=1.0 + +### VERSION 2.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=2.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=2.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=2.0 + +### People - Partial Update +PATCH {{baseUrl}}/api/people/1?api-version=2.0 +content-type: application/json +prefer: return=representation + +{"firstName":"John","lastName":"Doe"} + +### VERSION 3.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=3.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=3.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=3.0 + +### ------------------------------ BY URL SEGMENT ------------------------------ + +### VERSION 1.0 + +### Orders - Get All +GET {{baseUrl}}/api/v1/orders + +### Orders - Get by Key +GET {{baseUrl}}/api/v1/orders/1 \ No newline at end of file diff --git a/examples/AspNetCore/OData/ODataBasicExample/ODataBasicExample.csproj b/examples/AspNetCore/OData/ODataBasicExample/ODataBasicExample.csproj index 45e10dc9..ed77dfd1 100644 --- a/examples/AspNetCore/OData/ODataBasicExample/ODataBasicExample.csproj +++ b/examples/AspNetCore/OData/ODataBasicExample/ODataBasicExample.csproj @@ -4,6 +4,10 @@ net10.0 + + + + diff --git a/examples/AspNetCore/OData/ODataBasicExample/README.md b/examples/AspNetCore/OData/ODataBasicExample/README.md new file mode 100644 index 00000000..d90b29cc --- /dev/null +++ b/examples/AspNetCore/OData/ODataBasicExample/README.md @@ -0,0 +1,4 @@ +# ASP.NET Core with OData Basic Example + +This example project illustrates a bare bones, basic setup using OData endpoints. Launch the project and try the +[example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNetCore/OData/ODataConventionsExample/Configuration/OrderModelConfiguration.cs b/examples/AspNetCore/OData/ODataConventionsExample/Configuration/OrderModelConfiguration.cs index c757921a..b6d9388b 100644 --- a/examples/AspNetCore/OData/ODataConventionsExample/Configuration/OrderModelConfiguration.cs +++ b/examples/AspNetCore/OData/ODataConventionsExample/Configuration/OrderModelConfiguration.cs @@ -13,7 +13,7 @@ private static EntityTypeConfiguration ConfigureCurrent( ODataModelBuilde { var order = builder.EntitySet( "Orders" ).EntityType; - order.HasKey( p => p.Id ); + order.HasKey( p => p.Id ).Select(); return order; } diff --git a/examples/AspNetCore/OData/ODataConventionsExample/Configuration/PersonModelConfiguration.cs b/examples/AspNetCore/OData/ODataConventionsExample/Configuration/PersonModelConfiguration.cs index 5ebaa0db..89958bd4 100644 --- a/examples/AspNetCore/OData/ODataConventionsExample/Configuration/PersonModelConfiguration.cs +++ b/examples/AspNetCore/OData/ODataConventionsExample/Configuration/PersonModelConfiguration.cs @@ -20,7 +20,7 @@ private static EntityTypeConfiguration ConfigureCurrent( ODataModelBuild { var person = builder.EntitySet( "People" ).EntityType; - person.HasKey( p => p.Id ); + person.HasKey( p => p.Id ).Select(); return person; } diff --git a/examples/AspNetCore/OData/ODataConventionsExample/Examples.http b/examples/AspNetCore/OData/ODataConventionsExample/Examples.http new file mode 100644 index 00000000..55e26437 --- /dev/null +++ b/examples/AspNetCore/OData/ODataConventionsExample/Examples.http @@ -0,0 +1,55 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:5000 + +### ------------------------------ BY QUERY STRING ------------------------------ + +### VERSION 1.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=1.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=1.0&$select=firstName,lastName + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=1.0 + +### VERSION 2.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=2.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=2.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=2.0 + +### People - Partial Update +PATCH {{baseUrl}}/api/people/1?api-version=2.0 +content-type: application/json +prefer: return=representation + +{"firstName":"John","lastName":"Doe"} + +### VERSION 3.0 + +### People - Get All +GET {{baseUrl}}/api/people?api-version=3.0 + +### People - Get All with $select +GET {{baseUrl}}/api/people?api-version=3.0&$select=firstName,lastName,email + +### People - Get by Key +GET {{baseUrl}}/api/people/1?api-version=3.0 + +### ------------------------------ BY URL SEGMENT ------------------------------ + +### VERSION 1.0 + +### Orders - Get All +GET {{baseUrl}}/api/v1/orders + +### Orders - Get by Key +GET {{baseUrl}}/api/v1/orders/1 \ No newline at end of file diff --git a/examples/AspNetCore/OData/ODataConventionsExample/ODataConventionsExample.csproj b/examples/AspNetCore/OData/ODataConventionsExample/ODataConventionsExample.csproj index 45e10dc9..ed77dfd1 100644 --- a/examples/AspNetCore/OData/ODataConventionsExample/ODataConventionsExample.csproj +++ b/examples/AspNetCore/OData/ODataConventionsExample/ODataConventionsExample.csproj @@ -4,6 +4,10 @@ net10.0 + + + + diff --git a/examples/AspNetCore/OData/ODataConventionsExample/README.md b/examples/AspNetCore/OData/ODataConventionsExample/README.md new file mode 100644 index 00000000..615e0a2f --- /dev/null +++ b/examples/AspNetCore/OData/ODataConventionsExample/README.md @@ -0,0 +1,6 @@ +# ASP.NET Core with OData Conventions Example + +This example project illustrates using ASP.NET Core with OData by applying API version metadata with conventions +instead of attributes. This approach is useful if you prefer not to decorate controllers with API versions or in a +scenario where you might not have the ability to apply attributes yourself, such as in a plug-in model. Launch the +project and try the [example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNetCore/OData/ODataOpenApiExample/ODataOpenApiExample.csproj b/examples/AspNetCore/OData/ODataOpenApiExample/ODataOpenApiExample.csproj index d6b8d5a0..3726e694 100644 --- a/examples/AspNetCore/OData/ODataOpenApiExample/ODataOpenApiExample.csproj +++ b/examples/AspNetCore/OData/ODataOpenApiExample/ODataOpenApiExample.csproj @@ -7,12 +7,13 @@ - + + all runtime; build; native; contentfiles; analyzers; buildtransitive - - + + diff --git a/examples/AspNetCore/OData/ODataOpenApiExample/README.md b/examples/AspNetCore/OData/ODataOpenApiExample/README.md new file mode 100644 index 00000000..c7fb5016 --- /dev/null +++ b/examples/AspNetCore/OData/ODataOpenApiExample/README.md @@ -0,0 +1,7 @@ +# ASP.NET Core OData OpenAPI Example + +This example project illustrates using OData endpoints with [OpenAPI] and [Scalar]. Launch the project and try the +example requests to view an API in action. + +[OpenAPI]: https://www.openapis.org/ +[Scalar]: https://scalar.com/ \ No newline at end of file diff --git a/examples/AspNetCore/OData/SomeODataOpenApiExample/README.md b/examples/AspNetCore/OData/SomeODataOpenApiExample/README.md new file mode 100644 index 00000000..a70bbdbc --- /dev/null +++ b/examples/AspNetCore/OData/SomeODataOpenApiExample/README.md @@ -0,0 +1,8 @@ +# ASP.NET Core with Some OData OpenAPI Example + +This example project illustrates using standard ASP.NET Core controllers and OData query capabilities without fully +adhering to the OData protocol while also integrating with [OpenAPI] and [Scalar]. Launch the project and try the +example requests to view an API in action. + +[OpenAPI]: https://www.openapis.org/ +[Scalar]: https://scalar.com/ \ No newline at end of file diff --git a/examples/AspNetCore/OData/SomeODataOpenApiExample/SomeODataOpenApiExample.csproj b/examples/AspNetCore/OData/SomeODataOpenApiExample/SomeODataOpenApiExample.csproj index d6b8d5a0..3726e694 100644 --- a/examples/AspNetCore/OData/SomeODataOpenApiExample/SomeODataOpenApiExample.csproj +++ b/examples/AspNetCore/OData/SomeODataOpenApiExample/SomeODataOpenApiExample.csproj @@ -7,12 +7,13 @@ - + + all runtime; build; native; contentfiles; analyzers; buildtransitive - - + + diff --git a/examples/AspNetCore/WebApi/BasicExample/Examples.http b/examples/AspNetCore/WebApi/BasicExample/Examples.http new file mode 100644 index 00000000..68b06a70 --- /dev/null +++ b/examples/AspNetCore/WebApi/BasicExample/Examples.http @@ -0,0 +1,30 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:5000 + +### VERSION 1.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=1.0 + +### Hello World - Get +GET {{baseUrl}}/api/v1/helloworld + +### Hello World - Get by ID +GET {{baseUrl}}/api/v1/helloworld/42 + +### Hello World - Create +POST {{baseUrl}}/api/v1/helloworld + +### Multi-Versioned - Get +# note: this controller has a single, version interleaved implementation +GET {{baseUrl}}/api/v1/multiversioned + +### VERSION 2.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=2.0 + +### Multi-Versioned - Get +# note: this controller has a single, version interleaved implementation +GET {{baseUrl}}/api/v2/multiversioned \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/BasicExample/README.md b/examples/AspNetCore/WebApi/BasicExample/README.md new file mode 100644 index 00000000..e7fdcc83 --- /dev/null +++ b/examples/AspNetCore/WebApi/BasicExample/README.md @@ -0,0 +1,4 @@ +# ASP.NET Core Basic Example + +This example project illustrates a bare bones, basic setup using standard ASP.NET Core controllers. Launch the project +and try the [example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/ByNamespaceExample/Examples.http b/examples/AspNetCore/WebApi/ByNamespaceExample/Examples.http new file mode 100644 index 00000000..f8037525 --- /dev/null +++ b/examples/AspNetCore/WebApi/ByNamespaceExample/Examples.http @@ -0,0 +1,55 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:5000 + +### ------------------------------ BY QUERY STRING ------------------------------ + +### VERSION 1.0 + +### Agreements - Get by ID +GET {{baseUrl}}/agreements/42?api-version=1.0 + +### Orders - Get by ID +GET {{baseUrl}}/orders/42?api-version=1.0 + +### VERSION 2.0 + +### Agreements - Get by ID +GET {{baseUrl}}/agreements/42?api-version=2.0 + +### Orders - Get by ID +GET {{baseUrl}}/orders/42?api-version=2.0 + +### VERSION 3.0 + +### Agreements - Get by ID +GET {{baseUrl}}/agreements/42?api-version=3.0 + +### Orders - Get by ID +GET {{baseUrl}}/orders/42?api-version=3.0 + +### ------------------------------ BY URL SEGMENT ------------------------------ + +### VERSION 1.0 + +### Agreements - Get by ID +GET {{baseUrl}}/v1/agreements/42 + +### Orders - Get by ID +GET {{baseUrl}}/v1/orders/42 + +### VERSION 2.0 + +### Agreements - Get by ID +GET {{baseUrl}}/v2/agreements/42 + +### Orders - Get by ID +GET {{baseUrl}}/v2/orders/42 + +### VERSION 3.0 + +### Agreements - Get by ID +GET {{baseUrl}}/v3/agreements/42 + +### Orders - Get by ID +GET {{baseUrl}}/v3/orders/42 \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/ByNamespaceExample/README.md b/examples/AspNetCore/WebApi/ByNamespaceExample/README.md new file mode 100644 index 00000000..7b049311 --- /dev/null +++ b/examples/AspNetCore/WebApi/ByNamespaceExample/README.md @@ -0,0 +1,9 @@ +# ASP.NET Core Version By Namespace Convention Example + +This example project illustrates using ASP.NET Core controllers which have their API version applied using the +[version by .NET namespace convention][wiki] instead of attributes. This approach is useful if you prefer not to +decorate controllers with API versions and have them automatically versioned using the .NET namespace that defines +their type. Launch the project and try the [example requests](Examples.http) to view an API in action. + + +[wiki]: https://github.com/dotnet/aspnet-api-versioning/wiki/API-Version-Conventions#version-by-namespace-convention \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/ConventionsExample/Examples.http b/examples/AspNetCore/WebApi/ConventionsExample/Examples.http new file mode 100644 index 00000000..00c4b1c4 --- /dev/null +++ b/examples/AspNetCore/WebApi/ConventionsExample/Examples.http @@ -0,0 +1,30 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:5000 + +### VERSION 1.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=1.0 + +### Hello World - Get +GET {{baseUrl}}/api/v1/helloworld + +### Hello World - Get by ID +GET {{baseUrl}}/api/v1/helloworld/42 + +### VERSION 2.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=2.0 + +### Hello World - Get +GET {{baseUrl}}/api/v2/helloworld + +### Hello World - Get by ID +GET {{baseUrl}}/api/v2/helloworld/42 + +### VERSION 3.0 + +### Values - Get All +GET {{baseUrl}}/api/values?api-version=3.0 \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/ConventionsExample/README.md b/examples/AspNetCore/WebApi/ConventionsExample/README.md new file mode 100644 index 00000000..9e5305a9 --- /dev/null +++ b/examples/AspNetCore/WebApi/ConventionsExample/README.md @@ -0,0 +1,6 @@ +# ASP.NET Core Conventions Example + +This example project illustrates using ASP.NET Core controllers by applying API version metadata with conventions +instead of attributes. This approach is useful if you prefer not to decorate controllers with API versions or in a +scenario where you might not have the ability to apply attributes yourself, such as in a plug-in model. Launch the +project and try the [example requests](Examples.http) to view an API in action. \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/MinimalApiExample/Examples.http b/examples/AspNetCore/WebApi/MinimalApiExample/Examples.http new file mode 100644 index 00000000..160cfd1e --- /dev/null +++ b/examples/AspNetCore/WebApi/MinimalApiExample/Examples.http @@ -0,0 +1,25 @@ +# For more info on HTTP files go to https://aka.ms/vs/httpfile + +@baseUrl = http://localhost:5000 + +### VERSION 1.0 + +### Weather Forecast - Get All +GET {{baseUrl}}/weatherforecast?api-version=1.0 + +### Weather Forecast - Remove (Version-Neutral) +DELETE {{baseUrl}}/weatherforecast?api-version=1.0 + +### VERSION 2.0 + +### Weather Forecast - Get All +GET {{baseUrl}}/weatherforecast?api-version=2.0 + +### Weather Forecast - Update +POST {{baseUrl}}/weatherforecast?api-version=2.0 +content-type: application/json + +{"date":"2026-02-22T15:00:00-08:00","temperatureC":12,"temperatureF":54,"summary":"Chilly"} + +### Weather Forecast - Remove (Version-Neutral) +DELETE {{baseUrl}}/weatherforecast?api-version=2.0 \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/MinimalApiExample/Properties/launchSettings.json b/examples/AspNetCore/WebApi/MinimalApiExample/Properties/launchSettings.json index 2d820045..2321ba99 100644 --- a/examples/AspNetCore/WebApi/MinimalApiExample/Properties/launchSettings.json +++ b/examples/AspNetCore/WebApi/MinimalApiExample/Properties/launchSettings.json @@ -14,7 +14,7 @@ "dotnetRunMessages": true, "launchBrowser": true, "launchUrl": "weatherforecast?api-version=1.0", - "applicationUrl": "https://localhost:5145;http://localhost:5144", + "applicationUrl": "https://localhost:5001;http://localhost:5000", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" } diff --git a/examples/AspNetCore/WebApi/MinimalApiExample/README.md b/examples/AspNetCore/WebApi/MinimalApiExample/README.md new file mode 100644 index 00000000..8a048e86 --- /dev/null +++ b/examples/AspNetCore/WebApi/MinimalApiExample/README.md @@ -0,0 +1,4 @@ +# ASP.NET Core Minimal API Example + +This example project illustrates using ASP.NET Core _Minimal APIs_. Launch the project and try the example requests to +view an API in action. \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/MinimalOpenApiExample/MinimalOpenApiExample.csproj b/examples/AspNetCore/WebApi/MinimalOpenApiExample/MinimalOpenApiExample.csproj index 9b0fe311..0c742552 100644 --- a/examples/AspNetCore/WebApi/MinimalOpenApiExample/MinimalOpenApiExample.csproj +++ b/examples/AspNetCore/WebApi/MinimalOpenApiExample/MinimalOpenApiExample.csproj @@ -7,12 +7,12 @@ - + all runtime; build; native; contentfiles; analyzers; buildtransitive - - + + diff --git a/examples/AspNetCore/WebApi/MinimalOpenApiExample/Properties/launchSettings.json b/examples/AspNetCore/WebApi/MinimalOpenApiExample/Properties/launchSettings.json index 31870801..b8319ba1 100644 --- a/examples/AspNetCore/WebApi/MinimalOpenApiExample/Properties/launchSettings.json +++ b/examples/AspNetCore/WebApi/MinimalOpenApiExample/Properties/launchSettings.json @@ -13,7 +13,7 @@ "dotnetRunMessages": true, "launchBrowser": true, "launchUrl": "scalar", - "applicationUrl": "https://localhost:5145;http://localhost:5144", + "applicationUrl": "https://localhost:5001;http://localhost:5000", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" } diff --git a/examples/AspNetCore/WebApi/MinimalOpenApiExample/README.md b/examples/AspNetCore/WebApi/MinimalOpenApiExample/README.md new file mode 100644 index 00000000..c07ed60e --- /dev/null +++ b/examples/AspNetCore/WebApi/MinimalOpenApiExample/README.md @@ -0,0 +1,7 @@ +# ASP.NET Core Minimal API OpenAPI Example + +This example project illustrates using ASP.NET Core _Minimal APIs_ with [OpenAPI] and [Scalar]. Launch the project and +try the example requests to view an API in action. + +[OpenAPI]: https://www.openapis.org/ +[Scalar]: https://scalar.com/ \ No newline at end of file diff --git a/examples/AspNetCore/WebApi/OpenApiExample/OpenApiExample.csproj b/examples/AspNetCore/WebApi/OpenApiExample/OpenApiExample.csproj index 9b0fe311..0c742552 100644 --- a/examples/AspNetCore/WebApi/OpenApiExample/OpenApiExample.csproj +++ b/examples/AspNetCore/WebApi/OpenApiExample/OpenApiExample.csproj @@ -7,12 +7,12 @@ - + all runtime; build; native; contentfiles; analyzers; buildtransitive - - + + diff --git a/examples/AspNetCore/WebApi/OpenApiExample/README.md b/examples/AspNetCore/WebApi/OpenApiExample/README.md new file mode 100644 index 00000000..6c80e9cc --- /dev/null +++ b/examples/AspNetCore/WebApi/OpenApiExample/README.md @@ -0,0 +1,7 @@ +# ASP.NET Core OpenAPI Example + +This example project illustrates using standard ASP.NET Core controllers with [OpenAPI] and [Scalar]. Launch the +project and try the example requests to view an API in action. + +[OpenAPI]: https://www.openapis.org/ +[Scalar]: https://scalar.com/ \ No newline at end of file diff --git a/examples/Directory.Packages.props b/examples/Directory.Packages.props new file mode 100644 index 00000000..fa0294ae --- /dev/null +++ b/examples/Directory.Packages.props @@ -0,0 +1,20 @@ + + + + + true + + + + + + + + + + + + + + + \ No newline at end of file