daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2558 from domaindrivendev/update-swagger-docs 

Update swagger tutorial to reflect latest Swashbuckle changes
pull/2586/head
Shayne Boyer 2017-01-23 11:21:23 -08:00 committed by GitHub
parent 4cd10bfcce 49f9c9b8b0
commit b22ac2b516
5 changed files with 59 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
aspnetcore/tutorials/web-api-help-pages-using-swagger.md
View File

@ -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<ITodoRepository, TodoRepository>();
// 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:<random_port>/swagger/ui`
This document is used to drive the Swagger UI which can be viewed by navigating to `http://localhost:<random_port>/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 <https://github.com/domaindrivendev/Ahoy/tree/master/test/WebSites/CustomizedUi/wwwroot/swagger/ui>`_ 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 <https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/1.0.0-rc1/test/WebSites/CustomIndexHtml/wwwroot/swagger/index.html>`_ 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)
@ -319,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*

25
aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/Startup.cs
View File

@ -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<ITodoRepository, TodoRepository>();
// 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

4
aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/project.json
View File

@ -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": { },

0
aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/custom.css → aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/custom.css
View File

5
aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/ui/index.html → aspnetcore/tutorials/web-api-help-pages-using-swagger/sample/src/TodoApi/wwwroot/swagger/index.html
View File

@ -54,7 +54,7 @@
clientId: "your-client-id",
clientSecret: "your-client-secret-if-required",
realm: "your-realms",
appName: "your-app-name",
appName: "your-app-name",
scopeSeparator: ",",
additionalQueryStringParams: {}
});
@ -86,12 +86,9 @@
</head>
<body class="swagger-section">
<div id="header">
<h1>ToDo API Documentation</h1>
</div>
<div id="message-bar" class="swagger-ui-wrap" data-sw-translate>&nbsp;</div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>