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可以用于搜索各种文档。它提供可扩展的搜索,具有接近实时的搜索,并支持多租户。
相关文章
|
2月前
|
人工智能 监控 安全
自学记录鸿蒙 API 13:骨骼点检测应用Core Vision Skeleton Detection
骨骼点检测技术能够从图片中识别出人体的关键骨骼点位置,如头部、肩部、手肘等,广泛应用于运动健身指导、游戏交互、医疗辅助、安全监控等领域。我决定深入学习HarmonyOS Next API 13中的Skeleton Detection API,并开发一个简单的骨骼点检测应用。通过理解API核心功能、项目初始化与配置、实现检测功能、构建用户界面,以及性能优化和功能扩展,逐步实现这一技术的应用。未来计划将其应用于健身指导和智能监控领域,探索与其他AI能力的结合,开发更智能的解决方案。如果你也对骨骼点检测感兴趣,不妨一起进步!
176 9
|
2月前
|
人工智能 搜索推荐 API
自学记录鸿蒙API 13:实现人脸比对Core Vision Face Comparator
在完成文本识别和人脸检测项目后,我深入学习了HarmonyOS Next API 13中的Core Vision Face Comparator API,开发了一个简单的人脸比对工具。该API能进行高精度人脸比对并给出相似度评分,应用场景广泛,如照片分类、身份认证、个性化服务等。通过初始化服务、加载图片、实现比对功能和构建用户界面,最终实现了可靠的人脸比对功能。未来计划将此技术应用于更复杂的场景,如照片管理和个性化服务,并探索与其他AI能力的结合。如果你也对人脸比对感兴趣,不妨从简单的比对功能开始,逐步实现自己的创意!
131 61
|
2月前
|
人工智能 监控 安全
自学记录鸿蒙 API 13:实现人脸检测 Core Vision Face Detector
本文介绍了基于HarmonyOS Next API 13中的Core Vision Face Detector API实现人脸检测小应用的过程。通过研究发现,该API不仅支持人脸检测框的定位,还能识别关键点(如眼睛、鼻子和嘴角位置)及人脸姿态信息。文章详细记录了开发历程,包括项目初始化、权限配置、图像加载与人脸检测、用户界面设计,以及性能优化和功能扩展的思路。应用场景涵盖身份验证、照片管理和实时交互等。未来计划将技术应用于智能照片管理工具,提供更高效的照片分类体验。欢迎对人脸检测技术感兴趣的读者一起探讨和进步。
134 7
|
2月前
|
人工智能 自然语言处理 文字识别
自学记录鸿蒙API 13:实现智能文本识别Core Vision Text Recognition
在完成语音助手项目后,我尝试了HarmonyOS Next API 13中的Core Vision Text Recognition API,体验其强大的文本识别功能。该API支持多语言高精度识别,能快速将图像中的文本提取为结构化信息,适用于文档扫描、票据管理和实时翻译等场景。通过权限配置、初始化服务、实现识别功能和构建用户界面,我完成了文本识别应用的开发,并探索了性能优化与功能扩展。鸿蒙生态的强大支持让开发者能更便捷地实现复杂功能。未来计划将此技术应用于实际项目,如票据管理或实时翻译工具。如果你也对文本识别感兴趣,不妨一起探索!
93 11
|
2月前
|
开发框架 算法 中间件
ASP.NET Core 中的速率限制中间件
在ASP.NET Core中,速率限制中间件用于控制客户端请求速率,防止服务器过载并提高安全性。通过`AddRateLimiter`注册服务,并配置不同策略如固定窗口、滑动窗口、令牌桶和并发限制。这些策略可在全局、控制器或动作级别应用,支持自定义响应处理。使用中间件`UseRateLimiter`启用限流功能,并可通过属性禁用特定控制器或动作的限流。这有助于有效保护API免受滥用和过载。 欢迎关注我的公众号:Net分享 (239字符)
64 1
|
2月前
|
开发框架 .NET 开发者
简化 ASP.NET Core 依赖注入(DI)注册-Scrutor
Scrutor 是一个简化 ASP.NET Core 应用程序中依赖注入(DI)注册过程的开源库,支持自动扫描和注册服务。通过简单的配置,开发者可以轻松地从指定程序集中筛选、注册服务,并设置其生命周期,同时支持服务装饰等高级功能。适用于大型项目,提高代码的可维护性和简洁性。仓库地址:&lt;https://github.com/khellang/Scrutor&gt;
61 5
|
2月前
|
开发框架 缓存 .NET
GraphQL 与 ASP.NET Core 集成:从入门到精通
本文详细介绍了如何在ASP.NET Core中集成GraphQL,包括安装必要的NuGet包、创建GraphQL Schema、配置GraphQL服务等步骤。同时,文章还探讨了常见问题及其解决方法,如处理复杂查询、错误处理、性能优化和实现认证授权等,旨在帮助开发者构建灵活且高效的API。
59 3
|
3月前
|
开发框架 .NET C#
在 ASP.NET Core 中创建 gRPC 客户端和服务器
本文介绍了如何使用 gRPC 框架搭建一个简单的“Hello World”示例。首先创建了一个名为 GrpcDemo 的解决方案,其中包含一个 gRPC 服务端项目 GrpcServer 和一个客户端项目 GrpcClient。服务端通过定义 `greeter.proto` 文件中的服务和消息类型,实现了一个简单的问候服务 `GreeterService`。客户端则通过 gRPC 客户端库连接到服务端并调用其 `SayHello` 方法,展示了 gRPC 在 C# 中的基本使用方法。
65 5
在 ASP.NET Core 中创建 gRPC 客户端和服务器
|
1天前
|
JSON API 数据格式
阿里巴巴商品详情接口(阿里巴巴 API 系列)
在电商开发中,获取阿里巴巴商品详情信息对数据分析、竞品研究等至关重要。通过调用其商品详情接口,开发者可获取标题、价格、图片、描述等数据,满足多种业务需求。接口采用HTTPS协议,支持GET/POST请求,返回JSON格式数据。示例代码展示了如何使用Python的requests库进行接口请求,需传递商品ID和访问令牌。实际应用时,请依据官方文档调整参数并确保安全性。
27 10
|
2天前
|
JSON API 数据格式
eBay商品详情接口(ebay API系列)
eBay 商品详情接口是电商从业者、开发者和数据分析师获取商品详细信息的重要工具,涵盖标题、价格、库存、卖家信息等。使用前需在 eBay 开发者平台注册并获取 API 凭证,通过 HTTP GET 请求调用接口,返回 JSON 格式数据。Python 示例代码展示了如何发送请求并解析响应,确保合法合规使用数据。
32 12

热门文章

最新文章