Add Web API controller definition doc

aspnetcore/web-api/define-controller/samples/README.md

@@ -0,0 +1,12 @@
+# ASP.NET Core Web API Controller Sample
+
+This sample app consists of the following projects:
+
+- **WebApiSample.Api**: An ASP.NET Core 2.1 project targeting .NET Core 2.1.
+- **WebApiSample.Api.Pre21**: An ASP.NET Core 2.0 project targeting .NET Core 2.0.
+- **WebApiSample.DataAccess**: A .NET Standard 2.0 class library serving as a data access tier for the 2 Web API projects.
+
+This sample illustrates variations of Web API controller creation:
+
+- [Derive class from ControllerBase](https://docs.microsoft.com/en-us/aspnet/core/web-api/define-controller#derive-class-from-controllerbase)
+- [Annotate class with ApiControllerAttribute](https://docs.microsoft.com/en-us/aspnet/core/web-api/define-controller#annotate-class-with-apicontrollerattribute)

aspnetcore/web-api/define-controller/samples/WebApiSample.Api.Pre21/Controllers/PetsController.cs

@@ -0,0 +1,58 @@
+using Microsoft.AspNetCore.Mvc;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using WebApiSample.DataAccess.Models;
+using WebApiSample.DataAccess.Repositories;
+
+namespace WebApiSample.Api.Controllers
+{
+    #region snippet_PetsController
+    [Produces("application/json")]
+    [Route("api/[controller]")]
+    public class PetsController : ControllerBase
+    {
+        private readonly PetsRepository _repository;
+
+        public PetsController(PetsRepository repository)
+        {
+            _repository = repository;
+        }
+
+        [HttpGet]
+        [ProducesResponseType(typeof(IEnumerable<Pet>), 200)]
+        public IActionResult Get()
+        {
+            return Ok(_repository.GetPets());
+        }
+
+        [HttpGet("{id}")]
+        [ProducesResponseType(typeof(Pet), 200)]
+        [ProducesResponseType(404)]
+        public IActionResult GetById(int id)
+        {
+            if (!_repository.TryGetPet(id, out var pet))
+            {
+                return NotFound();
+            }
+
+            return Ok(pet);
+        }
+
+        [HttpPost]
+        [ProducesResponseType(typeof(Pet), 201)]
+        [ProducesResponseType(400)]
+        public async Task<IActionResult> CreateAsync([FromBody] Pet pet)
+        {
+            if (!ModelState.IsValid)
+            {
+                return BadRequest(ModelState);
+            }
+
+            await _repository.AddPetAsync(pet);
+
+            return CreatedAtAction(nameof(GetById),
+                new { id = pet.Id }, pet);
+        }
+    }
+    #endregion
+}

aspnetcore/web-api/define-controller/samples/WebApiSample.Api.Pre21/Controllers/ProductsController.cs

@@ -0,0 +1,72 @@
+using Microsoft.AspNetCore.Mvc;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using WebApiSample.DataAccess.Models;
+using WebApiSample.DataAccess.Repositories;
+
+namespace WebApiSample.Api.Pre21.Controllers
+{
+    #region snippet_ControllerSignature
+    [Route("api/[controller]")]
+    public class ProductsController : ControllerBase
+    #endregion
+    {
+        private readonly ProductsRepository _repository;
+
+        public ProductsController(ProductsRepository repository)
+        {
+            _repository = repository;
+        }
+
+        #region snippet_GetById
+        [HttpGet("{id}")]
+        [ProducesResponseType(typeof(Product), 200)]
+        [ProducesResponseType(404)]
+        public IActionResult GetById(int id)
+        {
+            if (!_repository.TryGetProduct(id, out var product))
+            {
+                return NotFound();
+            }
+
+            return Ok(product);
+        }
+        #endregion
+
+        #region snippet_BindingSourceAttributes
+        [HttpGet]
+        [ProducesResponseType(typeof(List<Product>), 200)]
+        public IActionResult Get([FromQuery] bool discontinuedOnly = false)
+        {
+            List<Product> products = null;
+
+            if (discontinuedOnly)
+            {
+                products = _repository.GetDiscontinuedProducts();
+            }
+            else
+            {
+                products = _repository.GetProducts();
+            }
+
+            return Ok(products);
+        }
+        #endregion
+
+        [HttpPost]
+        [ProducesResponseType(typeof(Product), 201)]
+        [ProducesResponseType(400)]
+        public async Task<IActionResult> CreateAsync([FromBody] Product product)
+        {
+            if (!ModelState.IsValid)
+            {
+                return BadRequest(ModelState);
+            }
+
+            await _repository.AddProductAsync(product);
+
+            return CreatedAtAction(nameof(GetById),
+                new { id = product.Id }, product);
+        }
+    }
+}

aspnetcore/web-api/define-controller/samples/WebApiSample.Api.Pre21/Program.cs

@@ -0,0 +1,25 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace WebApiSample.Api.Pre21
+{
+    public class Program
+    {
+        public static void Main(string[] args)
+        {
+            BuildWebHost(args).Run();
+        }
+
+        public static IWebHost BuildWebHost(string[] args) =>
+            WebHost.CreateDefaultBuilder(args)
+                .UseStartup<Startup>()
+                .Build();
+    }
+}

aspnetcore/web-api/define-controller/samples/WebApiSample.Api.Pre21/Startup.cs

@@ -0,0 +1,63 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Swashbuckle.AspNetCore.Swagger;
+using WebApiSample.DataAccess;
+using WebApiSample.DataAccess.Repositories;
+
+namespace WebApiSample.Api.Pre21
+{
+    public class Startup
+    {
+        public Startup(IConfiguration configuration)
+        {
+            Configuration = configuration;
+        }
+
+        public IConfiguration Configuration { get; }
+
+        // This method gets called by the runtime. Use this method to add services to the container.
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddScoped<ProductsRepository>();
+            services.AddScoped<PetsRepository>();
+
+            services.AddDbContext<ProductContext>(opt =>
+                opt.UseInMemoryDatabase("ProductInventory"));
+            services.AddDbContext<PetContext>(opt =>
+                opt.UseInMemoryDatabase("PetInventory"));
+
+            services.AddMvc();
+
+            services.AddSwaggerGen(c =>
+            {
+                c.SwaggerDoc("v1", new Info
+                {
+                    Title = "ASP.NET Core Pre-2.1 Web API",
+                    Version = "v1"
+                });
+
+                c.DescribeAllEnumsAsStrings();
+            });
+        }
+
+        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
+        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
+        {
+            if (env.IsDevelopment())
+            {
+                app.UseDeveloperExceptionPage();
+            }
+
+            app.UseSwagger();
+            app.UseSwaggerUI(c =>
+            {
+                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
+                c.RoutePrefix = string.Empty;
+            });
+            app.UseMvcWithDefaultRoute();
+        }
+    }
+}

aspnetcore/web-api/define-controller/samples/WebApiSample.Api.Pre21/WebApiSample.Api.Pre21.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>netcoreapp2.0</TargetFramework>
+    <ProjectUISubcaption>&lt;= ASP.NET Core 2.0</ProjectUISubcaption>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.7" />
+    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.3" />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="2.4.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\WebApiSample.DataAccess\WebApiSample.DataAccess.csproj" />
+  </ItemGroup>
+
+</Project>

aspnetcore/web-api/define-controller/samples/WebApiSample.Api.Pre21/appsettings.Development.json

@@ -0,0 +1,10 @@
+{
+  "Logging": {
+    "IncludeScopes": false,
+    "LogLevel": {
+      "Default": "Debug",
+      "System": "Information",
+      "Microsoft": "Information"
+    }
+  }
+}

aspnetcore/web-api/define-controller/samples/WebApiSample.Api.Pre21/appsettings.json

@@ -0,0 +1,15 @@
+{
+  "Logging": {
+    "IncludeScopes": false,
+    "Debug": {
+      "LogLevel": {
+        "Default": "Warning"
+      }
+    },
+    "Console": {
+      "LogLevel": {
+        "Default": "Warning"
+      }
+    }
+  }
+}

aspnetcore/web-api/define-controller/samples/WebApiSample.Api/Controllers/MyBaseController.cs

@@ -0,0 +1,11 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace WebApiSample.Api.Controllers
+{
+    #region snippet_ControllerSignature
+    [ApiController]
+    public class MyBaseController
+    {
+    }
+    #endregion
+}

aspnetcore/web-api/define-controller/samples/WebApiSample.Api/Controllers/PetsController.cs

@@ -0,0 +1,55 @@
+using Microsoft.AspNetCore.Mvc;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using WebApiSample.DataAccess.Models;
+using WebApiSample.DataAccess.Repositories;
+
+namespace WebApiSample.Api.Controllers
+{
+    #region snippet_PetsController
+    [Produces("application/json")]
+    [Route("api/[controller]")]
+    public class PetsController : ControllerBase
+    {
+        private readonly PetsRepository _repository;
+
+        public PetsController(PetsRepository repository)
+        {
+            _repository = repository;
+        }
+
+        [HttpGet]
+        public ActionResult<List<Pet>> Get()
+        {
+            return _repository.GetPets();
+        }
+
+        [HttpGet("{id}")]
+        [ProducesResponseType(404)]
+        public ActionResult<Pet> GetById(int id)
+        {
+            if (!_repository.TryGetPet(id, out var pet))
+            {
+                return NotFound();
+            }
+
+            return pet;
+        }
+
+        [HttpPost]
+        [ProducesResponseType(400)]
+        public async Task<ActionResult<Pet>> CreateAsync(Pet pet)
+        {
+            if (!ModelState.IsValid)
+            {
+                return BadRequest(ModelState);
+            }
+
+            await _repository.AddPetAsync(pet);
+
+            return CreatedAtAction(nameof(GetById),
+                new { id = pet.Id }, pet);
+        }
+    }
+    #endregion
+}