在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的支持:
public 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方法中,加入以下代码:
public 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也是一种同类产品,有兴趣的朋友可以去它们各自的官网了解一下。
在ASP.NET Core Web API上使用Swagger提供API文档的更多相关文章
- Core Web API上使用Swagger提供API文档
在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的AP ...
- 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档
博客搬到了fresky.github.io - Dawei XU,请各位看官挪步.最新的一篇是:用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档.
- Web Api使用Swagger提供在线文档
1.添加Swashbuckle引用 2.生成XML文件 3.添加XML解析,在接口添加注释信息 4.运行项目输入地址 http://localhost:58254/swagger
- asp.net core web的导入导出excel功能
这里主要记录下asp.net core web页面上进行导入导出excel的操作. 主要是导入,因为现在使用的很多前端框架(例如kendo ui)本身就有导出的功能. 这里使用到EPPlus.Core ...
- Asp.Net Core Web Api图片上传(一)集成MongoDB存储实例教程
Asp.Net Core Web Api图片上传及MongoDB存储实例教程(一) 图片或者文件上传相信大家在开发中应该都会用到吧,有的时候还要对图片生成缩略图.那么如何在Asp.Net Core W ...
- ASP.NET Core WEB API 使用element-ui文件上传组件el-upload执行手动文件文件,并在文件上传后清空文件
前言: 从开始学习Vue到使用element-ui-admin已经有将近快两年的时间了,在之前的开发中使用element-ui上传组件el-upload都是直接使用文件选取后立即选择上传,今天刚好做了 ...
- Docker容器环境下ASP.NET Core Web API应用程序的调试
本文主要介绍通过Visual Studio 2015 Tools for Docker – Preview插件,在Docker容器环境下,对ASP.NET Core Web API应用程序进行调试.在 ...
- 在docker中运行ASP.NET Core Web API应用程序
本文是一篇指导快速演练的文章,将介绍在docker中运行一个ASP.NET Core Web API应用程序的基本步骤,在介绍的过程中,也会对docker的使用进行一些简单的描述.对于.NET Cor ...
- ASP.NET Core Web API Cassandra CRUD 操作
在本文中,我们将创建一个简单的 Web API 来实现对一个 “todo” 列表的 CRUD 操作,使用 Apache Cassandra 来存储数据,在这里不会创建 UI ,Web API 的测试将 ...
随机推荐
- AES加密
package com.edu.hpu; import java.math.BigInteger; import java.security.MessageDigest; import java.se ...
- UWP开发之Template10实践二:拍照功能你合理使用了吗?(TempState临时目录问题)
最近在忙Asp.Net MVC开发一直没空更新UWP这块,不过有时间的话还是需要将自己的经验和大家分享下,以求共同进步. 在上章[UWP开发之Template10实践:本地文件与照相机文件操作的MVV ...
- bootstrap-fileinput 简单使用
bootstrap-fileinput 是一款图片/文件上传 bootstrap 插件,简单示例代码: <!DOCTYPE html> <html> <head> ...
- C++标准库实现WAV文件读写
在上一篇文章RIFF和WAVE音频文件格式中对WAV的文件格式做了介绍,本文将使用标准C++库实现对数据为PCM格式的WAV文件的读写操作,只使用标准C++库函数,不依赖于其他的库. WAV文件结构 ...
- Python学习
Python基础教程 网易云课堂-零基础入门学习Python
- ILJMALL project过程中遇到Fragment嵌套问题:IllegalArgumentException: Binary XML file line #23: Duplicate id
出现场景:当点击"分类"再返回"首页"时,发生error退出 BUG描述:Caused by: java.lang.IllegalArgumentExcep ...
- asp.net core 负载均衡集群搭建(centos7+nginx+supervisor+kestrel)
概述 本文目的是搭建三台asp.net core 集群, 并配上 nginx做负载均衡 首先准备要运行的源码 http://pan.baidu.com/s/1c20x0bA 准备三台服务器(或则虚 ...
- 树莓派3B的食用方法-1(装系统 网线ssh连接)
首先要有一个树莓派3B , 在某宝买就行, 这东西基本上找到假货都难,另外国产和英国也没什么差别,差不多哪个便宜买哪个就行. 不要买店家的套餐,一个是配的东西有些不需要,有的质量也不好. 提示:除了G ...
- 【腾讯Bugly干货分享】动态链接库加载原理及HotFix方案介绍
本文来自于腾讯bugly开发者社区,非经作者同意,请勿转载,原文地址:http://dev.qq.com/topic/57bec216d81f2415515d3e9c 作者:陈昱全 引言 随着项目中动 ...
- 企业IT管理员IE11升级指南【17】—— F12 开发者工具
企业IT管理员IE11升级指南 系列: [1]—— Internet Explorer 11增强保护模式 (EPM) 介绍 [2]—— Internet Explorer 11 对Adobe Flas ...