From 6e1b240033292f64787fcb7d982d3020debc9161 Mon Sep 17 00:00:00 2001 From: domaindrivendev Date: Fri, 20 Jan 2017 00:58:00 -0800 Subject: [PATCH 1/2] update swagger tutorial to reflect latest Swashbuckle changes --- .../web-api-help-pages-using-swagger.md | 78 ++++++++------- .../sample/src/TodoApi/Startup.cs | 25 +++-- .../sample/src/TodoApi/project.json | 4 +- .../src/TodoApi/wwwroot/swagger/ui/custom.css | 18 ---- .../src/TodoApi/wwwroot/swagger/ui/index.html | 98 ------------------- 5 files changed, 57 insertions(+), 166 deletions(-) delete mode 100644 aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/custom.css delete mode 100644 aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/index.html diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger.md b/aspnetcore/tutorials/web-api-help-pages-using-swagger.md index fa12aad5d3..8857f1ce01 100644 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger.md +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger.md @@ -20,9 +20,9 @@ By [Shayne Boyer](https://twitter.com/spboyer) Understanding the various methods of an API can be a challenge for a developer when building a consuming application. -Generating good documentation and help pages as a part of your Web API using [Swagger](http://swagger.io) with the .NET Core implementation [Swashbuckle](https://github.com/domaindrivendev/Ahoy) is as easy as adding a couple of NuGet packages and modifying the *Startup.cs*. +Generating good documentation and help pages as a part of your Web API using [Swagger](http://swagger.io) with the .NET Core implementation [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) is as easy as adding a couple of NuGet packages and modifying the *Startup.cs*. -* [Swashbuckle](https://github.com/domaindrivendev/Ahoy) is an open source project for generating Swagger documents for Web APIs that are built with ASP.NET Core MVC. +* [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) is an open source project for generating Swagger documents for Web APIs that are built with ASP.NET Core MVC. * [Swagger](http://swagger.io) is a machine readable representation of a RESTful API that enables support for interactive documentation, client SDK generation and discoverability. @@ -30,11 +30,13 @@ This tutorial builds on the sample on [Building Your First Web API with ASP.NET ## Getting Started -There are two core components to Swashbuckle +There are three main components to Swashbuckle -* *Swashbuckle.SwaggerGen* : provides the functionality to generate JSON Swagger documents that describe the objects, methods, return types, etc. +* *Swashbuckle.AspNetCore.Swagger* : a Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints. -* *Swashbuckle.SwaggerUI* : an embedded version of the Swagger UI tool which uses the above documents for a rich customizable experience for describing the Web API functionality and includes built in test harness capabilities for the public methods. +* *Swashbuckle.AspNetCore.SwaggerGen* : a Swagger generator that builds SwaggerDocument objects directly from your routes, controllers and models. Typically combined with the Swagger endpoint middleware to automatically expose Swagger JSON. + +* *Swashbuckle.AspNetCore.SwaggerUI* : an embedded version of the Swagger UI tool which interprets Swagger JSON to build a rich customizable experience for describing the Web API functionality, and includes built in test harness capabilities for the public methods. ## NuGet Packages @@ -43,16 +45,16 @@ You can add Swashbuckle with any of the following approaches: * From the Package Manager Console: ```bash -Install-Package Swashbuckle -Pre +Install-Package Swashbuckle.AspNetCore -Pre ``` * In Visual Studio: * Right click your project in Solution Explorer > Manage NuGet Packages - * Enter Swashbuckle in the search box + * Enter Swashbuckle.AspNetCore in the search box * Check "Include prerelease" * Set the Package source to nuget.org - * Tap the Swashbuckle package and then tap Install + * Tap the Swashbuckle.AspNetCore package and then tap Install ## Add and configure Swagger to the middleware @@ -71,8 +73,11 @@ public void ConfigureServices(IServiceCollection services) // Add our repository type services.AddSingleton(); - // Inject an implementation of ISwaggerProvider with defaulted settings applied - services.AddSwaggerGen(); + // Register the Swagger generator, defining one or more Swagger documents + services.AddSwaggerGen(c => + { + c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" }); + }); } // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. @@ -80,12 +85,14 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerF { app.UseMvcWithDefaultRoute(); - // Enable middleware to serve generated Swagger as a JSON endpoint + // Enable middleware to serve generated Swagger as a JSON endpoint. app.UseSwagger(); - // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.) - app.UseSwaggerUi(); - + // 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"); + }); } ``` @@ -162,7 +169,7 @@ In Visual Studio, press ^F5 to launch the app and navigate to `http://localhost: } ``` -This document is used to drive the Swagger UI which can be viewed by navigating to `http://localhost:/swagger/ui` +This document is used to drive the Swagger UI which can be viewed by navigating to `http://localhost:/swagger` ![Swagger UI](web-api-help-pages-using-swagger/_static/swagger-ui.png) @@ -176,22 +183,22 @@ Swagger is not only a simple way to represent the API, but has options for docum ### API Info and Description -The `ConfigureSwaggerGen` method can be used to add information such as the author, license, description. +The config. action passed to the `AddSwaggerGen` method can be used to add information such as the author, license, description. ```csharp -services.ConfigureSwaggerGen(options => - { - options.SingleApiVersion(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 = "", Url = "http://twitter.com/spboyer"}, - License = new License { Name = "Use under LICX", Url = "http://url.com" } - }); - }); - ``` +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 = "", Url = "http://twitter.com/spboyer"}, + License = new License { Name = "Use under LICX", Url = "http://url.com" } + }); +}); +``` The following image shows the Swagger UI displaying the version information added. @@ -297,15 +304,18 @@ Enable static files middleware. app.UseMvcWithDefaultRoute(); - // Enable middleware to serve generated Swagger as a JSON endpoint - app.UseSwagger(); + // Enable middleware to serve generated Swagger as a JSON endpoint. + app.UseSwagger(); - // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.) - app.UseSwaggerUi(); + // 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"); + }); } ``` -Acquire the core *index.html* file used for the Swagger UI page from the `Github repository `_ and put that in the `wwwroot/swagger/ui` folder and also create a new `custom.css` file in the same folder. +Acquire the core *index.html* file used for the Swagger UI page from the `Github repository `_ and put that in the `wwwroot/swagger` folder and also create a new `custom.css` file in the same folder. ![Solution Explorer showing Swagger UI custom css and html files within the wwwroot folder of the application](web-api-help-pages-using-swagger/_static/custom-files-folder-view.png) diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/Startup.cs b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/Startup.cs index ac032ec064..3eac006c38 100644 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/Startup.cs +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/Startup.cs @@ -5,8 +5,8 @@ using Microsoft.Extensions.Configuration; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; using TodoApi.Models; -using Swashbuckle.Swagger.Model; using Microsoft.Extensions.PlatformAbstractions; +using Swashbuckle.AspNetCore.Swagger; namespace TodoApi { @@ -25,13 +25,10 @@ namespace TodoApi // Add our repository type. services.AddSingleton(); - // Inject an implementation of ISwaggerProvider with defaulted settings applied. - services.AddSwaggerGen(); - - // Add the detail information for the API. - services.ConfigureSwaggerGen(options => + // Register the Swagger generator, defining one or more Swagger documents + services.AddSwaggerGen(c => { - options.SingleApiVersion(new Info + c.SwaggerDoc("v1", new Info { Version = "v1", Title = "ToDo API", @@ -41,12 +38,10 @@ namespace TodoApi License = new License { Name = "Use under LICX", Url = "http://url.com" } }); - //Determine base path for the application. - var basePath = PlatformServices.Default.Application.ApplicationBasePath; - //Set the comments path for the swagger json and ui. + var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "TodoApi.xml"); - options.IncludeXmlComments(xmlPath); + c.IncludeXmlComments(xmlPath); }); } @@ -60,9 +55,11 @@ namespace TodoApi // Enable middleware to serve generated Swagger as a JSON endpoint. app.UseSwagger(); - // Enable middleware to serve swagger-ui assets (HTML, JS, CSS etc.) - app.UseSwaggerUi(); - + // 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"); + }); } #endregion diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/project.json b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/project.json index 54a34e3c29..8064372c65 100644 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/project.json +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/project.json @@ -11,8 +11,8 @@ "Microsoft.AspNetCore.Server.IISIntegration": "1.0.0-*", "Microsoft.AspNetCore.Server.Kestrel": "1.0.0-*", "Microsoft.Extensions.Logging.Console": "1.0.0-*", - "Swashbuckle": "6.0.0-beta902", - "Microsoft.AspNetCore.StaticFiles": "1.0.0-*" + "Microsoft.AspNetCore.StaticFiles": "1.0.0-*", + "Swashbuckle.AspNetCore": "1.0.0-rc1" }, "frameworks": { "net451": { }, diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/custom.css b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/custom.css deleted file mode 100644 index 26d311c5ac..0000000000 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/custom.css +++ /dev/null @@ -1,18 +0,0 @@ - -.swagger-section #header -{ - border-bottom: 1px solid #000000; - font-style: normal; - font-weight: 400; - font-family: "Segoe UI Light","Segoe WP Light","Segoe UI","Segoe WP",Tahoma,Arial,sans-serif; - background-color: black; -} - -.swagger-section #header h1 -{ - text-align: center; - font-size: 20px; - color: white; -} - - diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/index.html b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/index.html deleted file mode 100644 index c6972c7bf5..0000000000 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/index.html +++ /dev/null @@ -1,98 +0,0 @@ - - - - - - ToDo API - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-
- - \ No newline at end of file From 49f9c9b8b07f397c0b7756a1cbe939caef6d72ea Mon Sep 17 00:00:00 2001 From: domaindrivendev Date: Sun, 22 Jan 2017 13:03:34 -0800 Subject: [PATCH 2/2] force add referenced wwwroot files for swagger sample app --- .../web-api-help-pages-using-swagger.md | 2 +- .../src/TodoApi/wwwroot/swagger/custom.css | 18 ++++ .../src/TodoApi/wwwroot/swagger/index.html | 95 +++++++++++++++++++ 3 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/custom.css create mode 100644 aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/index.html diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger.md b/aspnetcore/tutorials/web-api-help-pages-using-swagger.md index 8857f1ce01..db9a282a96 100644 --- a/aspnetcore/tutorials/web-api-help-pages-using-swagger.md +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger.md @@ -329,7 +329,7 @@ The following CSS provides a simple sample of a custom header title to the page. *custom.css file* -[!code-css[Main](web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/custom.css)] +[!code-css[Main](web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/custom.css)] *index.html body* diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/custom.css b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/custom.css new file mode 100644 index 0000000000..26d311c5ac --- /dev/null +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/custom.css @@ -0,0 +1,18 @@ + +.swagger-section #header +{ + border-bottom: 1px solid #000000; + font-style: normal; + font-weight: 400; + font-family: "Segoe UI Light","Segoe WP Light","Segoe UI","Segoe WP",Tahoma,Arial,sans-serif; + background-color: black; +} + +.swagger-section #header h1 +{ + text-align: center; + font-size: 20px; + color: white; +} + + diff --git a/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/index.html b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/index.html new file mode 100644 index 0000000000..176afae76c --- /dev/null +++ b/aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/index.html @@ -0,0 +1,95 @@ + + + + + + ToDo API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 
+
+ + \ No newline at end of file