Merge pull request #5 from Mathavana/develop

MathavanN · web-flow · commit 8d2eb9d439d4 · 2019-03-20T21:45:03.000+08:00
Develop - API Version
diff --git a/README.md b/README.md
@@ -1,13 +1,15 @@
 # ASP.NET Core Web API development
 
-We will try to create an api application using asp.net core.
-- Maninly using repository pattern, generics, LINQ, Entity framework core
+We will try to create an API application using asp.net core.
+- Mainly using repository pattern, generics, LINQ, Entity framework core
 - Main business logic implemented in InMemeory Database (plan to use MSSQL DB)
 - ASP NET Identity, JWT Authentication implemented in a separate DB
 - Swagger for API Document
+- API Version
 
-Next ToDo List:
+### Next ToDo List:
 - Role Based Authentication/Authorization
+- Standard response for both error/success results
 - Logging
 - Global Error Handling
 - Dockerization
diff --git a/Supermarket/Extensions/ServiceExtensions.cs b/Supermarket/Extensions/ServiceExtensions.cs
@@ -2,6 +2,9 @@
 using Microsoft.AspNetCore.Authentication.JwtBearer;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Identity;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Versioning;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
@@ -13,8 +16,11 @@
 using Supermarket.Persistent.Context;
 using Supermarket.Persistent.Contracts;
 using Supermarket.Persistent.Repositories;
+using Supermarket.Swagger;
 using Swashbuckle.AspNetCore.Swagger;
 using System;
+using System.Collections.Generic;
+using System.Linq;
 using System.Text;
 
 namespace Supermarket.Extensions
@@ -66,28 +72,34 @@ public static void ConfigureAutoMapper(this IServiceCollection services)
             services.AddAutoMapper();
         }
 
-        public static void ConfigureSwagger(this IServiceCollection services)
+        public static void ConfigureSwagger(this IServiceCollection services, Type type)
         {
-            services.AddSwaggerGen(c =>
+            services.AddSwaggerGen(options =>
             {
-                c.SwaggerDoc("v1", new Info
+                // Resolve the temprary IApiVersionDescriptionProvider service  
+                var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
+
+                // Add a swagger document for each discovered API version  
+                foreach (var description in provider.ApiVersionDescriptions)
+                {
+                    options.SwaggerDoc(description.GroupName, SwaggerInfo.CreateInfoForApiVersion(description, type));
+                }
+
+                // Define the BearerAuth scheme that's in use
+                options.AddSecurityDefinition("Bearer", new ApiKeyScheme()
+                {
+                    Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
+                    Name = "Authorization",
+                    In = "header",
+                    Type = "apiKey"
+                });
+                options.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>>
                 {
-                    Title = "Supermarket API",
-                    Version = "v1",
-                    Description = "A simple example ASP.NET Core Web API",
-                    TermsOfService = "None",
-                    Contact = new Contact
-                    {
-                        Name = "Mathavan N",
-                        Email = "mathavan@gmail.com",
-                        Url = "https://github.com/Mathavana"
-                    },
-                    License = new License
-                    {
-                        Name = "Use under LICX",
-                        Url = "https://example.com/license"
-                    }
+                    { "Bearer", Enumerable.Empty<string>() },
                 });
+
+                // Add a custom filter for setting the default values  
+                options.OperationFilter<SwaggerDefaultValues>();
             });
         }
 
@@ -111,16 +123,16 @@ public static void ConfigurePasswordPolicy(this IServiceCollection services)
         public static void ConfigureAuthentication(this IServiceCollection services, IConfiguration configuration)
         {
             var key = Encoding.UTF8.GetBytes(configuration["ApplicationSettings:JWT_Secret"].ToString());
-            services.AddAuthentication(x =>
+            services.AddAuthentication(options =>
             {
-                x.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
-                x.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
-                x.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
-            }).AddJwtBearer(x =>
+                options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
+                options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
+                options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
+            }).AddJwtBearer(options =>
             {
-                x.RequireHttpsMetadata = false;
-                x.SaveToken = false;
-                x.TokenValidationParameters = new TokenValidationParameters
+                options.RequireHttpsMetadata = false; //only for DEV ENV
+                options.SaveToken = false;
+                options.TokenValidationParameters = new TokenValidationParameters
                 {
                     ValidateIssuerSigningKey = true,
                     IssuerSigningKey = new SymmetricSecurityKey(key),
@@ -130,5 +142,28 @@ public static void ConfigureAuthentication(this IServiceCollection services, ICo
                 };
             });
         }
+
+        public static void ConfigureApiVersioning(this IServiceCollection services)
+        {
+            services.AddApiVersioning(options =>
+            {
+                options.ReportApiVersions = true;
+                options.DefaultApiVersion = new ApiVersion(1, 0);
+                options.AssumeDefaultVersionWhenUnspecified = true;
+                //options.ApiVersionReader = new MediaTypeApiVersionReader();
+                options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);
+            });
+        }
+
+        public static void ConfigureVersionedApiExplorer(this IServiceCollection services)
+        {
+            services.AddVersionedApiExplorer(options =>
+            {
+                //The format of the version added to the route URL
+                options.GroupNameFormat = "'v'VVV";
+                //Tells swagger to replace the version in the controller route
+                options.SubstituteApiVersionInUrl = true;
+            });
+        }
     }
 }
diff --git a/Supermarket/Startup.cs b/Supermarket/Startup.cs
@@ -2,6 +2,7 @@
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.HttpOverrides;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Newtonsoft.Json.Serialization;
@@ -44,17 +45,20 @@ public void ConfigureServices(IServiceCollection services)
 
             services.AddMvc().AddJsonOptions(options =>
             {
-                //Force Camel Case to JSON
                 options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
             }).SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
 
+            services.ConfigureVersionedApiExplorer();
+
+            services.ConfigureApiVersioning();
+
             services.ConfigureAutoMapper();
 
-            services.ConfigureSwagger();
+            services.ConfigureSwagger(this.GetType());
         }
 
         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
-        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
+        public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)
         {
             if (env.IsDevelopment())
             {
@@ -85,9 +89,13 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env)
 
             // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
             // specifying the Swagger JSON endpoint.
-            app.UseSwaggerUI(c =>
+            app.UseSwaggerUI(options =>
             {
-                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Supermarket API V1");
+                //Build a swagger endpoint for each discovered API version  
+                foreach (var description in provider.ApiVersionDescriptions)
+                {
+                    options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
+                }
             });
         }
     }
diff --git a/Supermarket/Supermarket.csproj b/Supermarket/Supermarket.csproj
@@ -5,9 +5,17 @@
     <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
   </PropertyGroup>
 
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
+    <DocumentationFile></DocumentationFile>
+    <OutputPath></OutputPath>
+  </PropertyGroup>
+
   <ItemGroup>
     <PackageReference Include="AutoMapper.Extensions.Microsoft.DependencyInjection" Version="6.0.0" />
     <PackageReference Include="Microsoft.AspNetCore.App" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.ApiExplorer" Version="2.2.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="3.1.2" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer" Version="3.2.0" />
     <PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.2.0" PrivateAssets="All" />
     <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.2.0" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="4.0.1" />
diff --git a/Supermarket/Swagger/SwaggerDefaultValues.cs b/Supermarket/Swagger/SwaggerDefaultValues.cs
@@ -0,0 +1,44 @@
+﻿using Swashbuckle.AspNetCore.Swagger;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using System.Linq;
+
+namespace Supermarket.Swagger
+{
+    public class SwaggerDefaultValues : IOperationFilter
+    {
+        /// <summary>  
+        /// Applies the filter to the specified operation using the given context.  
+        /// </summary>  
+        /// <param name="operation">The operation to apply the filter to.</param>  
+        /// <param name="context">The current operation filter context.</param>  
+        public void Apply(Operation operation, OperationFilterContext context)
+        {
+            if (operation.Parameters == null)
+            {
+                return;
+            }
+            foreach (var parameter in operation.Parameters.OfType<NonBodyParameter>())
+            {
+                var description = context.ApiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);
+                var routeInfo = description.RouteInfo;
+
+                if (parameter.Description == null)
+                {
+                    parameter.Description = description.ModelMetadata?.Description;
+                }
+
+                if (routeInfo == null)
+                {
+                    continue;
+                }
+
+                if (parameter.Default == null)
+                {
+                    parameter.Default = routeInfo.DefaultValue;
+                }
+
+                parameter.Required |= !routeInfo.IsOptional;
+            }
+        }
+    }
+}
diff --git a/Supermarket/Swagger/SwaggerInfo.cs b/Supermarket/Swagger/SwaggerInfo.cs
@@ -0,0 +1,33 @@
+﻿using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Swashbuckle.AspNetCore.Swagger;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using System.Threading.Tasks;
+
+namespace Supermarket.Swagger
+{
+    public static class SwaggerInfo
+    {
+        public static Info CreateInfoForApiVersion(ApiVersionDescription description, Type type)
+        {
+            var info = new Info()
+            {
+                Title = $"{type.Assembly.GetCustomAttribute<AssemblyProductAttribute>().Product} {description.ApiVersion}",
+                Version = description.ApiVersion.ToString(),
+                Description = "A simple example ASP.NET Core Web API",
+                TermsOfService = "None",
+                Contact = new Contact { Name = "Mathavan N", Email = "mathavan@gmail.com", Url = "https://github.com/Mathavana" },
+                License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
+            };
+
+            if (description.IsDeprecated)
+            {
+                info.Description += " This API version has been deprecated.";
+            }
+
+            return info;
+        }
+    }
+}
diff --git a/Supermarket/V1/Controllers/AboutController.cs b/Supermarket/V1/Controllers/AboutController.cs
@@ -0,0 +1,16 @@
+﻿using Microsoft.AspNetCore.Mvc;
+
+namespace Supermarket.V1.Controller
+{
+    [ApiController]
+    [ApiVersion("1.0")]
+    [Route("api/v{version:apiVersion}/[controller]")]
+    public class AboutController : ControllerBase
+    {
+        [HttpGet]
+        public IActionResult Get()
+        {
+            return Ok(new { message = "This is about Api Version 1.0" });
+        }
+    }
+}
diff --git a/Supermarket/V1/Controllers/AccountController.cs b/Supermarket/V1/Controllers/AccountController.cs
@@ -2,10 +2,8 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Identity;
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.CodeAnalysis.Options;
 using Microsoft.Extensions.Options;
 using Microsoft.IdentityModel.Tokens;
-using Supermarket.Entites.Models;
 using Supermarket.Extensions;
 using Supermarket.Identity.Models;
 using Supermarket.Resources;
@@ -16,18 +14,19 @@
 using System.Text;
 using System.Threading.Tasks;
 
-namespace Supermarket.Controllers
+namespace Supermarket.V1.Controller
 {
-    [Route("api/[controller]")]
     [ApiController]
+    [ApiVersion("1.0")]
+    [Route("api/v{version:apiVersion}/[controller]")]
     public class AccountController : ControllerBase
     {
         private readonly UserManager<ApplicationUser> _userManager;
         private readonly SignInManager<ApplicationUser> _signInManager;
         private readonly ApplicationSettings _appSettings;
         private readonly IMapper _mapper;
 
-        public AccountController(UserManager<ApplicationUser> userManager, SignInManager<ApplicationUser> signInManager, 
+        public AccountController(UserManager<ApplicationUser> userManager, SignInManager<ApplicationUser> signInManager,
             IOptions<ApplicationSettings> appSettings, IMapper mapper)
         {
             _userManager = userManager;
diff --git a/Supermarket/V1/Controllers/CategoriesController.cs b/Supermarket/V1/Controllers/CategoriesController.cs
@@ -8,10 +8,12 @@
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
-namespace Supermarket.Controllers
+namespace Supermarket.V1.Controllers
 {
-    [Route("/api/[controller]")]
+    [ApiVersion("1.0")]
+    [Route("api/v{version:apiVersion}/[controller]")]
     [Authorize]
+    [ApiController]
     public class CategoriesController : ControllerBase
     {
         private readonly IServiceWrapper _serviceWrapper;
@@ -76,6 +78,5 @@ public async Task<IActionResult> DeleteAsync(int id)
             var categoryResource = _mapper.Map<Category, CategoryResource>(result.Category);
             return Ok(categoryResource);
         }
-
     }
 }
diff --git a/Supermarket/V1/Controllers/ProductsController.cs b/Supermarket/V1/Controllers/ProductsController.cs
@@ -7,10 +7,12 @@
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
-namespace Supermarket.Controllers
+namespace Supermarket.V1.Controllers
 {
-    [Route("/api/[controller]")]
+    [ApiVersion("1.0")]
+    [Route("api/v{version:apiVersion}/[controller]")]
     [Authorize]
+    [ApiController]
     public class ProductsController : ControllerBase
     {
         private readonly IServiceWrapper _serviceWrapper;
diff --git a/Supermarket/V2/Controllers/AboutController.cs b/Supermarket/V2/Controllers/AboutController.cs

Original file line number	Diff line number	Diff line change
`@@ -8,10 +8,12 @@`
`8`	`8`	`using System.Collections.Generic;`
`9`	`9`	`using System.Threading.Tasks;`
`10`	`10`
`11`		`-namespace Supermarket.Controllers`
	`11`	`+namespace Supermarket.V1.Controllers`
`12`	`12`	`{`
`13`		`- [Route("/api/[controller]")]`
	`13`	`+ [ApiVersion("1.0")]`
	`14`	`+ [Route("api/v{version:apiVersion}/[controller]")]`
`14`	`15`	`[Authorize]`
	`16`	`+ [ApiController]`
`15`	`17`	`public class CategoriesController : ControllerBase`
`16`	`18`	`{`
`17`	`19`	`private readonly IServiceWrapper _serviceWrapper;`
`@@ -76,6 +78,5 @@ public async Task<IActionResult> DeleteAsync(int id)`
`76`	`78`	`var categoryResource = _mapper.Map<Category, CategoryResource>(result.Category);`
`77`	`79`	`return Ok(categoryResource);`
`78`	`80`	`}`
`79`		`-`
`80`	`81`	`}`
`81`	`82`	`}`
Original file line number	Diff line number	Diff line change
`@@ -7,10 +7,12 @@`
`7`	`7`	`using System.Collections.Generic;`
`8`	`8`	`using System.Threading.Tasks;`
`9`	`9`
`10`		`-namespace Supermarket.Controllers`
	`10`	`+namespace Supermarket.V1.Controllers`
`11`	`11`	`{`
`12`		`- [Route("/api/[controller]")]`
	`12`	`+ [ApiVersion("1.0")]`
	`13`	`+ [Route("api/v{version:apiVersion}/[controller]")]`
`13`	`14`	`[Authorize]`
	`15`	`+ [ApiController]`
`14`	`16`	`public class ProductsController : ControllerBase`
`15`	`17`	`{`
`16`	`18`	`private readonly IServiceWrapper _serviceWrapper;`