ASP.NET CORE 1.0 MVC API 文档用 SWASHBUCKLE SWAGGER实现

本文涉及的产品
检索分析服务 Elasticsearch 版,2核4GB开发者规格 1个月
简介:
+关注继续查看

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.

SwaggerProjectConfig

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

aspnet5Mvc6Swagger_02

Links:

https://github.com/domaindrivendev/Swashbuckle

https://github.com/domaindrivendev/Ahoy

http://blog.sluijsveld.com/28/01/2016/CustomSwaggerUIField/

修改文档名称及路径:

复制代码
using System;
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,如需转载请自行联系原作者

相关实践学习
使用阿里云Elasticsearch体验信息检索加速
通过创建登录阿里云Elasticsearch集群,使用DataWorks将MySQL数据同步至Elasticsearch,体验多条件检索效果,简单展示数据同步和信息检索加速的过程和操作。
ElasticSearch 入门精讲
ElasticSearch是一个开源的、基于Lucene的、分布式、高扩展、高实时的搜索与数据分析引擎。根据DB-Engines的排名显示,Elasticsearch是最受欢迎的企业搜索引擎,其次是Apache Solr(也是基于Lucene)。 ElasticSearch的实现原理主要分为以下几个步骤: 用户将数据提交到Elastic Search 数据库中 通过分词控制器去将对应的语句分词,将其权重和分词结果一并存入数据 当用户搜索数据时候,再根据权重将结果排名、打分 将返回结果呈现给用户 Elasticsearch可以用于搜索各种文档。它提供可扩展的搜索,具有接近实时的搜索,并支持多租户。
相关文章
|
1月前
|
开发框架 NoSQL .NET
ASP.NET Core开发者指南(2022版路线图)
ASP.NET Core开发者指南(2022版路线图)
37 0
ASP.NET Core开发者指南(2022版路线图)
|
2月前
|
开发框架 移动开发 网络协议
ASP.NET Core 使用 Web Socket
ASP.NET Core 使用 Web Socket
25 0
|
2月前
|
开发框架 中间件 .NET
ASP.NET CORE 自定义中间件
ASP.NET CORE 自定义中间件
23 0
|
2月前
|
开发框架 前端开发 .NET
ASP.NET Core 使用Autofac
ASP.NET Core 使用Autofac
31 0
ASP.NET Core 使用Autofac
|
2月前
|
开发框架 .NET Linux
ASP.NET Core部署到linux(CentOS)
ASP.NET Core部署到linux(CentOS)
61 0
ASP.NET Core部署到linux(CentOS)
|
2月前
|
开发框架 .NET API
ASP.NET Core 部署到docker
ASP.NET Core 部署到docker
38 0
|
2月前
|
开发框架 .NET 数据安全/隐私保护
ASP.NET Core Kestrel部署HTTPS
ASP.NET Core Kestrel部署HTTPS1,在program.cs中CreateHostBuilder 替换成如下内容:public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .UseServ...
18 0
|
2月前
|
XML 开发框架 .NET
ASP.NET Core 使用记录3
解决Visual Studio报错 NETSDK1152: 找到了多个具有相同相对路径的发布输出文件原因:是项目多层引用(a引用了b、c,d引用了a、b、c),且被引用的项目生成了xml文件,发布时导致xml文件重复 ,但.net 6.0下会触发报错。解决:被引用项目不要生成xml文件【根本原因】;发布时,将C:\Program Files\dotnet\sdk\6.x的sdk移出C:\P...
18 0
|
2月前
|
开发框架 .NET API
ASP.NET Core 使用记录2
.net sdk 版本的切换版本更改命令:dotnet new globaljson --sdk-version 版本 --force CultureInfoSystem.Globalization 程序集下的类它提供有关特定区域性(对于非托管代码开发,则称为“区域设置”)的信息。 这些信息包括区域性的名称、书写系统、使用的日历、字符串的排序顺序以及对日期和数字的格式化设置。
19 0
 ASP.NET Core 使用记录2
|
2月前
|
开发框架 .NET Linux
ASP.NET Core 使用记录1
ASP.NET 项目启动 提示 ID为XXX的进程未启动原因:暂时不能明确。 解决方案:删除项目的 csproj 文件的WebProjectProperties节点内容。 <WebProjectProperties> <UseIIS>True</UseIIS> <AutoAssignPort>True</AutoAssignPort> ...
22 0
ASP.NET Core 使用记录1
热门文章
最新文章
相关产品
云迁移中心
推荐文章
更多