雷神王传,51看书网,毕业生简历
在前后端分离的大环境下，api接口文档成为了前后端交流的一个重点。swagger让开发人员摆脱了写接口文档的痛苦。
官方网址：
在.net core webapi中通过简单配置即可使用这一强大的功能。
1.新建一个api的项目
选择 api 项目
2.引入swagger包。.net core 中支持两个分别为swashbuckle和nswag。两者的配置大同小异。这里以swashbuckle为例。
方式1：选择工具——nuget包管理——管理解决方案的nuget包
搜索：swashbuckle.aspnetcore 安装即可
方式2：直接在程序包管理控制台输入：install-package swashbuckle.aspnetcore 回车即可安装
安装之后在项目的nuget包中就可以看到了
3.配置swagger中间件
3.1 在startup类configureservices方法中添加swagger服务并配置文档信息
我要评论 public void configureservices(iservicecollection services)
{
// 注册swagger服务
services.addswaggergen(c =>
{
// 添加文档信息
c.swaggerdoc("v1", new info { title = "corewebapi", version = "v1" });
});
services.addmvc().setcompatibilityversion(compatibilityversion.version_2_2);
}
3.2 在 startup类configure 方法中，启用中间件为生成的 json 文档和 swagger ui 提供服务
public void configure(iapplicationbuilder app, ihostingenvironment env)
{
if (env.isdevelopment())
{
app.usedeveloperexceptionpage();
}
else
{
// the default hsts value is 30 days. you may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.usehsts();
}
app.usehttpsredirection();
// 启用swagger中间件
app.useswagger();
// 配置swaggerui
app.useswaggerui(c =>
{
c.swaggerendpoint("/swagger/v1/swagger.json", "corewebapi");
});
app.usemvc();
}
右键项目属性，将url地址固定到某个端口
然后将启动项设置为当前项目，然后启动。
在根目录目前是没有东西的。下一步将在根目录处使用swaggerui
将routeprefix属性设置为空
app.usehttpsredirection();
// 启用swagger中间件
app.useswagger();
// 配置swaggerui
app.useswaggerui(c =>
{
c.swaggerendpoint("/swagger/v1/swagger.json", "corewebapi");
c.routeprefix = string.empty;
});
再次启动项目，swaggerui文档成功显示出来。整体简洁大方。
api的信息说明：传递给addswaggergen（）的方法可配置一些api的信息说明以及作者信息等，来展示到ui页面。修改addswaggergen（）方法。
// 注册swagger服务
services.addswaggergen(c =>
{
// 添加文档信息
c.swaggerdoc("v1", new info
{
title = "corewebapi",
version = "v1",
description="asp.net core webapi",
contact=new contact
{
name="jee",
email="xiaomaprincess@gmail.com"
}
});
});
展示对应的信息
4.启用xml注释。上边的效果只有一个简单说明，并没有我们在后台写的注释。启用xml注释之后可以轻松映射到ui界面方便前端开发人员理解。
右键当前项目——编辑****.csproj 的文件 在propertygroup标签组中添加如下两条
<generatedocumentationfile>true</generatedocumentationfile> <nowarn>$(nowarn);1591</nowarn>
这两句的大概意思就是启用xml注释，并忽略未写注释的警告。不添加1591如果某个方法未写 "///"各式的注释，vs会有警示的消息。
之后addswaggergen（）方法中读取xml文件路径并启用
// 注册swagger服务
services.addswaggergen(c =>
{
// 添加文档信息
c.swaggerdoc("v1", new info
{
title = "corewebapi",
version = "v1",
description="asp.net core webapi",
contact=new contact
{
name="jee",
email="xiaomaprincess@gmail.com"
}
});
// 使用反射获取xml文件。并构造出文件的路径
var xmlfile = $"{assembly.getexecutingassembly().getname().name}.xml";
var xmlpath = path.combine(appcontext.basedirectory, xmlfile);
// 启用xml注释. 该方法第二个参数启用控制器的注释，默认为false.
c.includexmlcomments(xmlpath,true);
});
再次启动项目，可以看到写的注释全部都映射出来了
text类的返回值也可以映射出来
models文件夹中的实体也可以映射在接口下方
总结： 在.net core中配置swagger非常之快速。但这也是堪堪达到可以用的程度，算是入门级别吧。
源码：github
https://github.com/xiaomaprincess/asp.netcore-webapi
如对本文有疑问，请在下面进行留言讨论，广大热心网友会与你互动！！ 点击进行留言回复
asp.net搭建博客，使用BlogEngine.NET+MySql搭建博客
网友评论