From f35329e7667f9455481e350f73eb27b89642eb55 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Thu, 31 May 2018 15:44:45 -0500 Subject: [PATCH 1/2] Fix Swashbuckle tutorial for 1.x apps --- .../getting-started-with-swashbuckle.md | 42 ++++++++--- .../2.0/TodoApi.Swashbuckle/Startup1x.cs | 71 +++++++++++++++++++ .../2.0/TodoApi.Swashbuckle/TodoApi.csproj | 2 +- .../2.1/TodoApi.Swashbuckle/TodoApi.csproj | 4 +- 4 files changed, 108 insertions(+), 11 deletions(-) create mode 100644 aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup1x.cs diff --git a/aspnetcore/tutorials/getting-started-with-swashbuckle.md b/aspnetcore/tutorials/getting-started-with-swashbuckle.md index f3a160f33069..5a3a895a380f 100644 --- a/aspnetcore/tutorials/getting-started-with-swashbuckle.md +++ b/aspnetcore/tutorials/getting-started-with-swashbuckle.md @@ -5,7 +5,7 @@ description: Learn how to add Swashbuckle to your ASP.NET Core web API project t manager: wpickett ms.author: scaddie ms.custom: mvc -ms.date: 05/08/2018 +ms.date: 05/31/2018 ms.prod: asp.net-core ms.technology: aspnet ms.topic: article @@ -15,12 +15,7 @@ uid: tutorials/get-started-with-swashbuckle By [Shayne Boyer](https://twitter.com/spboyer) and [Scott Addie](https://twitter.com/Scott_Addie) -::: moniker range="<= aspnetcore-2.0" -[View or download sample code](https://github.com/aspnet/Docs/tree/master/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle) ([how to download](xref:tutorials/index#how-to-download-a-sample)) -::: moniker-end -::: moniker range=">= aspnetcore-2.1" -[View or download sample code](https://github.com/aspnet/Docs/tree/master/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle) ([how to download](xref:tutorials/index#how-to-download-a-sample)) -::: moniker-end +[View or download sample code](https://github.com/aspnet/Docs/tree/master/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/) ([how to download](xref:tutorials/index#how-to-download-a-sample)) There are three main components to Swashbuckle: @@ -81,10 +76,15 @@ dotnet add TodoApi.csproj package Swashbuckle.AspNetCore Add the Swagger generator to the services collection in the `Startup.ConfigureServices` method: ::: moniker range="<= aspnetcore-2.0" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup2.cs?name=snippet_ConfigureServices&highlight=8-11)] + ::: moniker-end + ::: moniker range=">= aspnetcore-2.1" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/Startup2.cs?name=snippet_ConfigureServices&highlight=9-12)] + ::: moniker-end Import the following namespace to use the `Info` class: @@ -152,11 +152,22 @@ Suppress warnings by defining a semicolon-delimited list of warning codes to ign Configure Swagger to use the generated XML file. For Linux or non-Windows operating systems, file names and paths can be case-sensitive. For example, a *TodoApi.XML* file is valid on Windows but not CentOS. -::: moniker range="<= aspnetcore-2.0" +::: moniker range="<= aspnetcore-1.1" + +[!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup1x.cs?name=snippet_ConfigureServices&highlight=30-32)] + +::: moniker-end + +::: moniker range="= aspnetcore-2.0" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup.cs?name=snippet_ConfigureServices&highlight=30-32)] + ::: moniker-end + ::: moniker range=">= aspnetcore-2.1" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/Startup.cs?name=snippet_ConfigureServices&highlight=31-33)] + ::: moniker-end In the preceding code, [Reflection](/dotnet/csharp/programming-guide/concepts/reflection) is used to build an XML file name matching that of the Web API project. This approach ensures that the generated XML file name matches the project name. The [AppContext.BaseDirectory](/dotnet/api/system.appcontext.basedirectory#System_AppContext_BaseDirectory) property is used to construct a path to the XML file. @@ -201,10 +212,15 @@ The UI is driven by the generated JSON schema: Add a [\](/dotnet/csharp/programming-guide/xmldoc/remarks) element to the `Create` action method documentation. It supplements information specified in the `` element and provides a more robust Swagger UI. The `` element content can consist of text, JSON, or XML. ::: moniker range="<= aspnetcore-2.0" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Controllers/TodoController.cs?name=snippet_Create&highlight=4-14)] + ::: moniker-end + ::: moniker range=">= aspnetcore-2.1" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/Controllers/TodoController.cs?name=snippet_Create&highlight=4-14)] + ::: moniker-end Notice the UI enhancements with these additional comments: @@ -248,10 +264,15 @@ The presence of this attribute changes the UI behavior and alters the underlying Add the `[Produces("application/json")]` attribute to the API controller. Its purpose is to declare that the controller's actions support a response content type of *application/json*: ::: moniker range="<= aspnetcore-2.0" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Controllers/TodoController.cs?name=snippet_TodoController&highlight=1)] + ::: moniker-end + ::: moniker range=">= aspnetcore-2.1" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/Controllers/TodoController.cs?name=snippet_TodoController&highlight=1)] + ::: moniker-end The **Response Content Type** drop-down selects this content type as the default for the controller's GET actions: @@ -267,10 +288,15 @@ Consuming developers are most concerned with what's returned—specifically The `Create` action returns an HTTP 201 status code on success. An HTTP 400 status code is returned when the posted request body is null. Without proper documentation in the Swagger UI, the consumer lacks knowledge of these expected outcomes. Fix that problem by adding the highlighted lines in the following example: ::: moniker range="<= aspnetcore-2.0" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Controllers/TodoController.cs?name=snippet_Create&highlight=17,18,20,21)] + ::: moniker-end + ::: moniker range=">= aspnetcore-2.1" + [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/Controllers/TodoController.cs?name=snippet_Create&highlight=17,18,20,21)] + ::: moniker-end The Swagger UI now clearly documents the expected HTTP response codes: diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup1x.cs b/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup1x.cs new file mode 100644 index 000000000000..0a2231dc9476 --- /dev/null +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup1x.cs @@ -0,0 +1,71 @@ +// This is the Startup.cs file for an ASP.NET Core 1.x app. +using Microsoft.AspNetCore.Builder; +using Microsoft.EntityFrameworkCore; +using Microsoft.Extensions.DependencyInjection; +using Swashbuckle.AspNetCore.Swagger; +using System; +using System.IO; +using System.Reflection; +using TodoApi.Models; + +namespace TodoApi +{ + public class Startup1x + { + #region snippet_ConfigureServices + public void ConfigureServices(IServiceCollection services) + { + services.AddDbContext(opt => + opt.UseInMemoryDatabase("TodoList")); + services.AddMvc(); + + // Register the Swagger generator, defining 1 or more Swagger documents + services.AddSwaggerGen(c => + { + c.SwaggerDoc("v1", new Info + { + Version = "v1", + Title = "ToDo API", + Description = "A simple example ASP.NET Core Web API", + TermsOfService = "None", + Contact = new Contact + { + Name = "Shayne Boyer", + Email = string.Empty, + Url = "https://twitter.com/spboyer" + }, + License = new License + { + Name = "Use under LICX", + Url = "https://example.com/license" + } + }); + + // Set the comments path for the Swagger JSON and UI. + var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml"; + var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); + c.IncludeXmlComments(xmlPath); + }); + } + #endregion + + #region snippet_Configure + public void Configure(IApplicationBuilder app) + { + app.UseStaticFiles(); + + // Enable middleware to serve generated Swagger as a JSON endpoint. + app.UseSwagger(); + + // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), + // specifying the Swagger JSON endpoint. + app.UseSwaggerUI(c => + { + c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); + }); + + app.UseMvc(); + } + #endregion + } +} \ No newline at end of file diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/TodoApi.csproj b/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/TodoApi.csproj index 5b434c1465b9..f8c098a2550d 100644 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/TodoApi.csproj +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/TodoApi.csproj @@ -2,7 +2,7 @@ netcoreapp2.0 - Swashbuckle + Swashbuckle - ASP.NET Core 2.0 diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/TodoApi.csproj b/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/TodoApi.csproj index b8787970c64b..0b85e30e54ca 100644 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/TodoApi.csproj +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger/samples/2.1/TodoApi.Swashbuckle/TodoApi.csproj @@ -2,7 +2,7 @@ netcoreapp2.1 - Swashbuckle + Swashbuckle - ASP.NET Core 2.1 @@ -13,7 +13,7 @@ - + From e6dfda789855f6a2686aba7e1da19d8b92096103 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Thu, 31 May 2018 20:28:17 -0500 Subject: [PATCH 2/2] React to feedback --- aspnetcore/tutorials/getting-started-with-swashbuckle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/tutorials/getting-started-with-swashbuckle.md b/aspnetcore/tutorials/getting-started-with-swashbuckle.md index 5a3a895a380f..ee61152f2881 100644 --- a/aspnetcore/tutorials/getting-started-with-swashbuckle.md +++ b/aspnetcore/tutorials/getting-started-with-swashbuckle.md @@ -104,7 +104,7 @@ The Swagger UI can be found at `http://localhost:/swagger`. Explore the AP > > [!code-csharp[](../tutorials/web-api-help-pages-using-swagger/samples/2.0/TodoApi.Swashbuckle/Startup3.cs?name=snippet_UseSwaggerUI&highlight=4)] -## Customize & extend +## Customize and extend Swagger provides options for documenting the object model and customizing the UI to match your theme.