Core Web API上使用Swagger提供API文档
在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能。当设置IISExpress的默认启动路由到Swagger的API文档页面后,在IISExpress启动Web API站点后,会自动重定向到API文档页面,非常方便。这不仅让我能够快速省查API设计的合理性,同时从API的使用角度也为我自己提供了便捷。下图就是我的博客系统RESTful API的Swagger文档界面:
接下来,让我们一起看一下如何在ASP.NET Core Web API上实现这一基于Swagger的API文档页面。
实现步骤
创建ASP.NET Web API应用程序
这部分内容就不多说了,方法有很多,可以在安装了Visual Studio 2015/2017 Tools for .NET Core后,使用Visual Studio 2015或者2017直接创建ASP.NET Core的应用程序,也可以使用.NET Core SDK的dotnet new –t web命令在当前文件夹下新建Web项目。本文的演示将基于Visual Studio 2015进行介绍。
添加对Swashbuckle.SwaggerUi和Swashbuckle.SwaggerGen库的引用
- 在Web API项目上单击鼠标右键,选择Manage NuGet Packages:
- 在Visual Studio 2015 NuGet标签页中,在Browse(浏览)tab下,输入Swashbuckle.SwaggerUi,注意记得勾选“Include prerelease”选项:
- 安装上图中选中的包到项目中
- 用上述同样的方式安装Swashbuckle.SwaggerGen包到项目中
注意:目前两个包都还是处于beta的版本,所以需要勾选Include prerelease的选项。
打开XML文档功能
- 在Web API项目上点击鼠标右键,选择Properties(属性)选项:
- 在项目属性标签页中,切换到Build页面,同时打开XML documentation file选项:
- 此时会生成Web API项目代码的XML文档。于是,编译你的项目时会产生一系列的警告信息,因为你暂时还未完成代码的文档注释
修改Startup.cs文件
- 双击打开Startup.cs文件
- 在ConfigureServices方法中,加入以下代码,以增加对Swagger的支持:
1234567891011121314151617181920public
void
ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddMvc();
services.AddSwaggerGen();
services.ConfigureSwaggerGen(options =>
{
options.SingleApiVersion(
new
Swashbuckle.Swagger.Model.Info
{
Version =
"v1"
,
Title =
"My Web Application"
,
Description =
"RESTful API for My Web Application"
,
TermsOfService =
"None"
});
options.IncludeXmlComments(Path.Combine(PlatformServices.Default.Application.ApplicationBasePath,
"WebApplication14.XML"
));
// 注意:此处替换成所生成的XML documentation的文件名。
options.DescribeAllEnumsAsStrings();
});
}
- 在Configure方法中,加入以下代码:
12345678910public
void
Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection(
"Logging"
));
loggerFactory.AddDebug();
app.UseSwagger();
app.UseSwaggerUi();
app.UseMvc();
}
修改Web API项目首页重定向
- 在项目上展开Properties节点,双击launchSettings.json文件
- 根据需要,修改不同profile下的launchUrl的值,比如在本案例中,修改IIS Express节点下的launchUrl,将其改为下图中的值:
- 测试一下,在Visual Studio中,将Web API项目设置成启动项,然后直接Ctrl+F5启动项目,你将看到以下画面:
- 在项目中增加一些注释试试看?打开ValuesController.cs文件,增加一些注释:
- 再次运行站点,发现这些文档注释都体现在API页面中了:
- 我们还可以直接在API文档页面中进行API的调用测试:
总结
本文以Walkthrough的方式介绍了如何在ASP.NET Core Web API中增加Swagger API文档页面的功能,Swagger是一个非常棒的RESTful API设计、生成、文档化以及规范化工具,它基于YAML语言,并在官方提供了YAML语言的编辑器。开发人员可以通过各种编辑器,用YAML定义RESTful API的接口契约,同时还可以生成几十种编程语言的RESTful服务端和客户端代码(在上面的截图中,大家有没有留意到绿色背景标题栏中的swagger.json文件URL?下载这个文件,然后到官网的编辑器中导入后,即可立刻根据自己的开发语言,下载包含有我们的RESTful API实现的服务端框架和客户端调用代码)。这有点像SOAP Web Services时代的WSDL(Web Service描述语言)以及wsdl.exe、svcutil.exe等工具。除了Swagger,RAML也是一种同类产品,有兴趣的朋友可以去它们各自的官网了解一下。
Core Web API上使用Swagger提供API文档的更多相关文章
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- 【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】
swagger提供开发者文档 ======================================================== 作用:想使用swagger的同学,一定是想用它来做前后台 ...
- 【swagger】2.swagger提供开发者文档--返回统一格式篇【spring mvc】【spring boot】
接着上一篇来说, 不管正常返回结果还是后台出现异常,应该返回给前台统一的响应格式. 所以这一篇就为了应对解决这个问题. ======================================== ...
- Web Api使用Swagger提供在线文档
1.添加Swashbuckle引用 2.生成XML文件 3.添加XML解析,在接口添加注释信息 4.运行项目输入地址 http://localhost:58254/swagger
- 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档
博客搬到了fresky.github.io - Dawei XU,请各位看官挪步.最新的一篇是:用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档.
- asp.net core 使用 swagger 生成接口文档
参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...
- .net core 使用 swagger 生成接口文档
微软参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs= ...
- .Net Api 之如何使用Elasticsearch存储文档
.Net Api 之如何使用Elasticsearch存储文档 什么是Elasticsearch? Elasticsearch 是一个分布式.高扩展.高实时的搜索与数据分析引擎.它能很方便的使大量数据 ...
- Spring Boot 集成 Swagger 构建接口文档
在应用开发过程中经常需要对其他应用或者客户端提供 RESTful API 接口,尤其是在版本快速迭代的开发过程中,修改接口的同时还需要同步修改对应的接口文档,这使我们总是做着重复的工作,并且如果忘记修 ...
随机推荐
- cocoapods遇到的问题 (pod: command not found的问题)
在使用CocoaPod为项目添加第三方类库时,出现了-bash: pod: command not found的问题: 在网上看到了一位哥的方法:确实有效:
- 编译生成IOS开发使用的FFmpeg的过程
前言:本篇随笔纯属是参照<iOS 使用 FFmpeg>的过程,本人自己操作了一遍,但是本人记性不好,觉得这样的过程可以记录在博客中,以后需要可以快速回头翻阅细节.所以特地参考<iOS ...
- js 静态私有变量
特权方法:有权访问私有变量和私有函数的公有方法.在私有作用域中定义私有变量或函数,可以创建特权方法,如下: 示例1 (function(){ //私有变量和私有函数 var privateVariab ...
- TechEd2013 Shanghai Hol Session PPT Share
上个月去上海参加了TechEd 2013,并且参与了Hands-on-Lab环节,作为讲师引导大家完成<Local DB in WP8>实验的内容.由于实验的内容采用MVVM架构完成,因此 ...
- 在Eclipse中导入SVN库里的Maven项目
长期使用Intellij 对于Eclipse的东西都生疏了... 做了个小教程说明Eclipse下导入Maven工程的步骤以备不时之需 1. 安装maven插件 a) 下载maven http://m ...
- ORA-12154 & TNS-03505 案例分享
下面介绍一个工作中遇到的案例场景,应用服务器连接数据库出现"ORA-12154: TNS: 无法解析指定的连接标识符".一般情况下ORA-12541错误是很容易排除的,但是这次遇到 ...
- JAVA_OPTS
JAVA_OPTS ,顾名思义,是用来设置JVM相关运行参数的变量. JVM:JAVA_OPTS="-server -Xms2048m -Xmx2048m -Xss512k" -s ...
- 继续说一下2016里面的json功能(1)
首先先来测试数据,数据是使用之前的,就 不要在意这些细节了啊~ 借用上一篇的测试数据 ),Chinese int ,Math int) ,),(,),(,),(,null); 然后我们使用这个表里面生 ...
- 生成bat文件及sh文件
---windows下cmd执行java文件1.将project程序打成jar包2.新建文件夹--新建.bat文件3.bat文件内容:(config配置文件--lib用到的jar包,包括1的jar包) ...
- Eclipse和PyDev搭建完美Python开发环境(Windows篇)
目录安装Pythonpython for eclipse插件安装配置PyDev插件测试 安装Python从网站上下载最新的版本,从http://python.org/download/下载.安装过程与 ...