This article shows how to document your ASP.NET Core 1.0 MVC API using Swagger with Swashbuckle. Per default, it does not use your xml comments in the code and this needs to be configured if required.
Code: https://github.com/damienbod/AspNet5GeoElasticsearch
2016.07.03 Updated to ASP.NET Core RTM
2016.06.04 Updated to ASP.NET Core RC2 dotnet
Step 1: Add the required NuGet packages to the dependencies in the project.json file.
|
1
2
3
4
5
6
|
"dependencies"
: {
"Swashbuckle.SwaggerGen"
:
"6.0.0-beta901"
,
"Swashbuckle.SwaggerUi"
:
"6.0.0-beta901"
},
|
Step 2: Produce the .xml file which contains the xml comments when building. Click the produce outputs on build checkbox in your project file.
Or set the ProduceOutputsOnBuild property in the project xproj file.
|
1
|
<ProduceOutputsOnBuild>True</ProduceOutputsOnBuild>
|
Step 3: Configure Swashbuckle.SwaggerGen in the Startup class ConfigureServices method.
You need to define your path to the comments xml file, which can be found in the artifacts folder. This should be saved in a config file.
The ConfigureSwaggerDocument with OperationFilter method is required so that the xml comments are added to the documentation, and also ConfigureSwaggerSchema with ModelFilter
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
|
public
void
ConfigureServices(IServiceCollection services)
{
var
pathToDoc = Configuration[
"Swagger:Path"
];
services.AddMvc();
services.AddSwaggerGen();
services.ConfigureSwaggerGen(options =>
{
options.SingleApiVersion(
new
Info
{
Version =
"v1"
,
Title =
"Geo Search API"
,
Description =
"A simple api to search using geo location in Elasticsearch"
,
TermsOfService =
"None"
});
options.IncludeXmlComments(pathToDoc);
options.DescribeAllEnumsAsStrings();
});
services.AddScoped<ISearchProvider, SearchProvider>();
}
|
Step 4: Use swagger in the Startup class Configure method.
UseSwaggerGen and UseSwaggerUi
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
|
public
void
Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection(
"Logging"
));
loggerFactory.AddDebug();
if
(env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseBrowserLink();
}
else
{
app.UseExceptionHandler(
"/Home/Error"
);
}
app.UseStaticFiles();
app.UseMvc(routes =>
{
routes.MapRoute(
name:
"default"
,
template:
"{controller=Home}/{action=Index}/{id?}"
);
});
app.UseSwagger();
app.UseSwaggerUi();
}
|
Step 5: Create a Controller API with your documentation:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
using
Microsoft.AspNet.Mvc;
using
AspNet5GeoElasticsearch.ElasticsearchApi;
using
AspNet5GeoElasticsearch.Models;
using
Newtonsoft.Json;
using
Swashbuckle.SwaggerGen.Annotations;
namespace
AspNet5GeoElasticsearch.Controllers
{
/// <summary>
/// This class is used as an api for the search requests.
/// </summary>
[Route(
"api/[controller]"
)]
[Produces(
"application/json"
)]
public
class
SearchController : Controller
{
private
readonly
ISearchProvider _searchProvider;
public
SearchController(ISearchProvider searchProvider)
{
_searchProvider = searchProvider;
}
/// <summary>
/// This method returns the found documents from Elasticsearch
/// </summary>
/// <param name="maxDistanceInMeter">Distance in meters from your location</param>
/// <param name="centerLongitude">center Longitude </param>
/// <param name="centerLatitude">center Latitude </param>
/// <returns>All the documents which were found</returns>
[HttpGet]
[Produces(
typeof
(MapModel))]
[SwaggerResponse(System.Net.HttpStatusCode.OK, Type =
typeof
(MapModel))]
[Route(
"GeoSearch"
)]
public
ActionResult Search(
uint
maxDistanceInMeter,
double
centerLongitude,
double
centerLatitude)
{
var
searchResult = _searchProvider.SearchForClosest(maxDistanceInMeter, centerLongitude, centerLatitude);
var
mapModel =
new
MapModel
{
MapData = JsonConvert.SerializeObject(searchResult),
CenterLongitude = centerLongitude,
CenterLatitude = centerLatitude,
MaxDistanceInMeter = maxDistanceInMeter
};
return
Ok(mapModel);
}
/// <summary>
/// Inits the Elasticsearch documents
/// </summary>
[HttpPost]
[Route(
"InitData"
)]
public
ActionResult InitData()
{
initSearchEngine();
return
Ok();
}
private
void
initSearchEngine()
{
if
(!_searchProvider.MapDetailsIndexExists())
{
_searchProvider.InitMapDetailMapping();
_searchProvider.AddMapDetailData();
}
}
}
}
|
This can then be viewed using ./swagger/ui
http://localhost:21453/swagger/ui/index.html
Links:
https://github.com/domaindrivendev/Swashbuckle
https://github.com/domaindrivendev/Ahoy
http://blog.sluijsveld.com/28/01/2016/CustomSwaggerUIField/
修改文档名称及路径：
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Swashbuckle.Swagger.Model;
using Swashbuckle.SwaggerGen.Application;
namespace CoreApi
{
/// <summary>
///
/// </summary>
public class Startup
{
/// <summary>
/// 必须，不允许为空字符串
/// </summary>
string version = " v1 ";
/// <summary>
/// API文档路径
/// </summary>
string pathToDoc = Path.Combine(AppContext.BaseDirectory, " CoreApi.xml ");
/// <summary>
/// API项目名称
/// </summary>
string appName = " CoreApi ";
/// <summary>
///
/// </summary>
/// <param name="env"></param>
public Startup(IHostingEnvironment env)
{
appName = env.ApplicationName;
pathToDoc = Path.Combine(AppContext.BaseDirectory, string.Format( " {0}.xml ", env.ApplicationName));
var builder = new ConfigurationBuilder()
.SetBasePath(env.ContentRootPath)
.AddJsonFile( " appsettings.json ", optional: true, reloadOnChange: true)
.AddJsonFile($ " appsettings.{env.EnvironmentName}.json ", optional: true)
.AddEnvironmentVariables();
Configuration = builder.Build();
}
/// <summary>
///
/// </summary>
public IConfigurationRoot Configuration
{
get;
}
// This method gets called by the runtime. Use this method to add services to the container.
/// <summary>
///
/// </summary>
/// <param name="services"></param>
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddMvc();
services.AddSwaggerGen();
services.ConfigureSwaggerGen(options =>
{
options.SingleApiVersion( new Info
{
Version = version,
Title = appName,
Description = appName,
TermsOfService = " None ",
});
options.IncludeXmlComments(pathToDoc);
options.DescribeAllEnumsAsStrings();
});
// services.AddScoped<ISearchProvider, SearchProvider>();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
/// <summary>
///
/// </summary>
/// <param name="app"></param>
/// <param name="env"></param>
/// <param name="loggerFactory"></param>
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection( " Logging "));
loggerFactory.AddDebug();
app.UseSwagger( " help/{apiVersion}/api.json ");
app.UseSwaggerUi( " help ", string.Format( " /help/{0}/api.json ", version));
app.UseMvc();
}
}
}
本文转自94cool博客园博客，原文链接：http://www.cnblogs.com/94cool/p/5694881.html，如需转载请自行联系原作者
