ASP.NET CORE 1.0 MVC API 文档用 SWASHBUCKLE SWAGGER实现
from:https://damienbod.com/2015/12/13/asp-net-5-mvc-6-api-documentation-using-swagger/
代码生成工具: https://github.com/NSwag/NSwag
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;
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();
}
}
}
搜索
复制
ASP.NET CORE 1.0 MVC API 文档用 SWASHBUCKLE SWAGGER实现的更多相关文章
- 用VSCode开发一个asp.net core2.0+angular5项目(5): Angular5+asp.net core 2.0 web api文件上传
第一部分: http://www.cnblogs.com/cgzl/p/8478993.html 第二部分: http://www.cnblogs.com/cgzl/p/8481825.html 第三 ...
- 从头编写 asp.net core 2.0 web api 基础框架 (1)
工具: 1.Visual Studio 2017 V15.3.5+ 2.Postman (Chrome的App) 3.Chrome (最好是) 关于.net core或者.net core 2.0的相 ...
- 【转载】从头编写 asp.net core 2.0 web api 基础框架 (1)
工具: 1.Visual Studio 2017 V15.3.5+ 2.Postman (Chrome的App) 3.Chrome (最好是) 关于.net core或者.net core 2.0的相 ...
- ASP.NET Core 2.0 MVC项目实战
一.前言 毕业后入职现在的公司快有一个月了,公司主要的产品用的是C/S架构,再加上自己现在还在学习维护很老的delphi项目,还是有很多不情愿的.之前实习时主要是做.NET的B/S架构的项目,主要还是 ...
- asp.net core 3.0 MVC JSON 全局配置
asp.net core 3.0 MVC JSON 全局配置 System.Text.Json(default) startup配置代码如下: using System.Text.Encodings. ...
- 从头编写 asp.net core 2.0 web api 基础框架 (3)
第一部分:http://www.cnblogs.com/cgzl/p/7637250.html 第二部分:http://www.cnblogs.com/cgzl/p/7640077.html 之前我介 ...
- 【转载】从头编写 asp.net core 2.0 web api 基础框架 (3)
Github源码地址:https://github.com/solenovex/Building-asp.net-core-2-web-api-starter-template-from-scratc ...
- 从头编写asp.net core 2.0 web api 基础框架 (5) + 使用Identity Server 4建立Authorization Server (7) 可运行前后台源码
前台使用angular 5, 后台是asp.net core 2.0 web api + identity server 4. 从头编写asp.net core 2.0 web api 基础框架: 第 ...
- asp.net core 2.0 web api + Identity Server 4 + angular 5 可运行前后台源码
前台使用angular 5, 后台是asp.net core 2.0 web api + identity server 4. 从头编写asp.net core 2.0 web api 基础框架: 第 ...
随机推荐
- JavaScript学习13 JavaScript中的继承
JavaScript学习13 JavaScript中的继承 继承第一种方式:对象冒充 <script type="text/javascript"> //继承第一种方式 ...
- 通知 - NSNotificationCenter
1.每一个应用程序都有一个通知中心(NSNotificationCenter)实例,专门负责协助不同对象之间的消息通信: 2.任何一个对象都可以向通知中心发布通知(NSNotification), 描 ...
- intelliJ idea代码折叠
在intelliJ idea中不仅可以对类.方法等结构的代码进行折叠(ctrl+-)还可以自定义折叠代码.intelliJ支持两种风格的自定义代码折叠,如下: visual studio style ...
- 结对编程-地铁续(有种上个学期OO的既视感)
我们组比较特殊..三人结对 github:https://github.com/qingchanghan/WPFUI_Metro po一张照片: 石浩然,韩青长.陈彦吉 (台式机真的很高端,分屏贼帅) ...
- 基于微软平台IIS/ASP.NET开发的大型网站有哪些呢?
首先说明一下,本文绝不是要说Microsoft平台多么好,多么牛.只是要提醒一些LAMP/JAVA平台下的同志们,微软平台不至于像你们说的,和想象的那么不堪!只是你们自己不知道而已.同时,也希望广大M ...
- PHP判断访问者手机移动端还是PC端的函数,亲测好用
,用手机访问PC端WWW域名的时候,自动判断跳转到移动端,用电脑访问M域名手机网站的时候,自动跳转到PC端,我们团队在开发erdaicms二代旅游CMS网站管理系统的时候(http://www.erd ...
- Asp.net MVC中提交集合对象,实现Model绑定
Asp.net MVC中的Model自动绑定功能,方便了我们对于request中的数据的处理, 从客户端的请求数据,自动地以Action方法参数的形式呈现.有时候我们的Action方法中想要接收数组类 ...
- druid连接池异常
在从excel导入10W条数据到mysql中时,运行一段时间就会抛这个异常,连接池问题 org.springframework.transaction.CannotCreateTransactionE ...
- 由一个订单推送想到了ObservableCollection的神奇用法
最近在做taobao的一个卖家应用,需要订阅taobao的订单推送,示例代码如下: 看到上面的OnMessage场景之后,我突然就鬼使神差的在想最近写的一个服务,其中的一个功能是需要定时的轮询一个集合 ...
- 优化SQLServer——表和分区索引
概念: 简单地说,分区是将大型的对象(如表)分成更小的且易于管理的小块.分区的基本单位是行,需要注意的是与分区视图不同的地方时,分区必须位于同一个数据库内. 分区的原因: 对于非 ...