feat: Add Swagger and some initial examples of using of it

Author: drwatson1

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/App_Start/DependenciesConfig.cs

@@ -0,0 +1,27 @@
+using Microsoft.Extensions.DependencyInjection;
+using Swashbuckle.AspNetCore.Swagger;
+using System;
+using System.IO;
+using System.Reflection;
+
+namespace ReferenceProject
+{
+    public static class DependenciesConfig
+    {
+        public static IServiceCollection AddSwagger(this IServiceCollection services)
+        {
+            // Register the Swagger generator, defining 1 or more Swagger documents
+            services.AddSwaggerGen(c =>
+            {
+                c.SwaggerDoc(Constants.Swagger.Version, new Info { Title = Constants.Swagger.ApiName, Version = Constants.Swagger.Version });
+
+                // Set the comments path for the Swagger JSON and UI.
+                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
+                c.IncludeXmlComments(xmlPath);
+            });
+
+            return services;
+        }
+    }
+}

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/App_Start/MiddlewareConfig.cs

@@ -0,0 +1,24 @@
+using Microsoft.AspNetCore.Builder;
+
+namespace ReferenceProject
+{
+    public static class MiddlewareConfig
+    {
+        public static IApplicationBuilder UseSwaggerWithOptions(this IApplicationBuilder app)
+        {
+            // Enable middleware to serve generated Swagger as a JSON endpoint.
+            SwaggerBuilderExtensions.UseSwagger(app);
+
+            // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
+            // specifying the Swagger JSON endpoint.
+            app.UseSwaggerUI(c =>
+            {
+                // Uncomment this line if you want to access the Swagger UI as http://localhost:5000
+                // c.RoutePrefix = string.Empty;
+                c.SwaggerEndpoint(Constants.Swagger.EndPoint, Constants.Swagger.ApiName);
+            });
+
+            return app;
+        }
+    }
+}

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/Constants.cs

@@ -0,0 +1,12 @@
+namespace ReferenceProject
+{
+    public static class Constants
+    {
+        public static class Swagger
+        {
+            public static string EndPoint => $"/swagger/{Version}/swagger.json";
+            public static string ApiName => "My API";
+            public static string Version => "v1";
+        }
+    }
+}

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/Controllers/ProductsController.cs

@@ -1,5 +1,7 @@
 using AutoMapper;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Formatters;
 using ReferenceProject.Repo;
 using System;
 using System.Collections.Generic;
@@ -9,6 +11,7 @@ namespace ReferenceProject.Controllers
 {
     [Route("[controller]")]
     [ApiController]
+    [Produces("application/json")]
     public class ProductsController: ControllerBase
     {
         Repo.IProductsRepo ProductsRepo { get; }
@@ -20,21 +23,34 @@ public ProductsController(Repo.IProductsRepo productsRepo, IMapper mapper)
             ProductsRepo = productsRepo ?? throw new ArgumentNullException(nameof(productsRepo));
         }
 
+        /// <summary>
+        /// Get all products
+        /// </summary>
+        /// <response code="200">List of all of the products</response>
         [HttpGet]
         public IEnumerable<Dto.Product> Get()
         {
             return ProductsRepo.Get().Select(Mapper.Map<Dto.Product>);
         }
 
+        /// <summary>
+        /// Get product by id
+        /// </summary>
+        /// <param name="id">Product id</param>
+        /// <response code="200">Product with the specified id</response>
+        [ProducesResponseType(StatusCodes.Status404NotFound)]
         [HttpGet]
         [Route("{id}")]
         public Dto.Product GetById(int id)
         {
             return Mapper.Map<Dto.Product>(ProductsRepo.GetById(id));
         }
 
+        /// <summary>
+        /// Example of an exception handling
+        /// </summary>
         [HttpGet("ThrowAnException")]
-        public void ThrowAnException()
+        public IActionResult ThrowAnException()
         {
             throw new Exception("Example exception");
         }

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/Controllers/ValuesController.cs

@@ -5,25 +5,35 @@ namespace ReferenceProject.Controllers
 {
 #pragma warning disable RECS0154 // Parameter is never used
 
+    /// <summary>
+    /// Standart ASP.Net Core Example Controller
+    /// </summary>
     [Route("[controller]")]
     [ApiController]
+    [Produces("application/json")]
     public class ValuesController : ControllerBase
     {
-        // GET values
+        /// <summary>
+        /// Get values
+        /// </summary>
+        /// <response code="200">List of values</response>
         [HttpGet]
-        public ActionResult<IEnumerable<string>> Get()
+        public IEnumerable<string> Get()
         {
             return new string[] { "value1", "value2" };
         }
 
         // GET values/5
         [HttpGet("{id}")]
-        public ActionResult<string> Get(int id)
+        public string Get(int id)
         {
             return "value";
         }
 
-        // POST values
+        /// <summary>
+        /// Add new value
+        /// </summary>
+        /// <param name="value">New value</param>
         [HttpPost]
         public void Post([FromBody] string value)
         {

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/Dto/Product.cs

@@ -1,7 +1,13 @@
 namespace ReferenceProject.Dto
 {
+    /// <summary>
+    /// Model example: Product
+    /// </summary>
     public class Product
     {
+        /// <summary>
+        /// Product name
+        /// </summary>
         public string Name { get; set; }
     }
 }

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/ReferenceProject.csproj

@@ -6,6 +6,9 @@
 
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
     <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <WarningsAsErrors>NU1605</WarningsAsErrors>
+    <NoWarn>1701;1702;1591</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
@@ -25,6 +28,8 @@
     <PackageReference Include="Serilog.Settings.Configuration" Version="3.0.1" />
     <PackageReference Include="Serilog.Sinks.Console" Version="3.1.1" />
     <PackageReference Include="Serilog.Sinks.File" Version="4.0.0" />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="4.0.1" />
+    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="4.0.1" />
     <PackageReference Include="System.Net.Http" Version="4.3.4" />
   </ItemGroup>
 

ProjectTemplates/AspNetCore.WebApi/ReferenceProject/ReferenceProject/Startup.cs

@@ -1,5 +1,4 @@
-using System.IO;
-using Autofac;
+using Autofac;
 using Autofac.Configuration;
 using AutoMapper;
 using Microsoft.AspNetCore.Builder;
@@ -15,6 +14,7 @@
 using Newtonsoft.Json.Serialization;
 using ReferenceProject.Filters;
 using ReferenceProject.Modules;
+using System.IO;
 
 // TODO: Create and validate configuration in web.config:
 // https://www.talkingdotnet.com/how-to-increase-file-upload-size-asp-net-core/
@@ -37,7 +37,7 @@ public Startup(IConfiguration configuration, IHostingEnvironment env, ILogger<St
                 DotNetEnv.Env.Load();
             }
 
-            JsonConvert.DefaultSettings = () => 
+            JsonConvert.DefaultSettings = () =>
                 new JsonSerializerSettings()
                 {
                     ContractResolver = new CamelCasePropertyNamesContractResolver(),
@@ -49,7 +49,7 @@ public Startup(IConfiguration configuration, IHostingEnvironment env, ILogger<St
 #else
                     Formatting = Formatting.None
 #endif
-            };
+                };
         }
 
         public IConfiguration Configuration { get; }
@@ -71,6 +71,8 @@ public void ConfigureServices(IServiceCollection services)
                     options.Filters.Add(new ValidateModelFilter());
                     options.Filters.Add(new CacheControlFilter());
                 })
+                .AddApiExplorer()
+                .AddJsonFormatters()
                 .AddJsonOptions(options =>
                 {
                     options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;
@@ -85,7 +87,9 @@ public void ConfigureServices(IServiceCollection services)
                 })
                 .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
 
-            services.AddAutoMapper();
+            services
+                .AddAutoMapper()
+                .AddSwagger();
         }
 
         // ConfigureContainer is where you can register things directly
@@ -122,8 +126,9 @@ public void Configure(IApplicationBuilder app/*, IHostingEnvironment env*/)
                 .AllowAnyHeader()
                 .AllowCredentials());
 
-            // Options verb handler must be added after CORS
-            app.UseOptionsVerbHandler();
+            app
+                .UseOptionsVerbHandler()    // Options verb handler must be added after CORS
+                .UseSwaggerWithOptions();
 
             app.UseMvcWithDefaultRoute();