[aspnetcore.apidoc]一款很不错的api文档生成工具
aspnetcore.apidoc
简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger
最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api文档角度来说,从前后端文档沟通角度来讲
apidoc的表现形式,要比swagger简单的多,效果也要好很多。
不要和我说什么swagger现在已经是一个标准了,其实swagger的坑很多,就单说枚举类型抓取上,就显示的很无奈,下面我会创建项目,写一个接口,拿这个接口举例,同时用apidoc和swagger展示其文档效果,对比一下孰优孰劣。
当然我这里并没有引战的意识,大家选用swagger,也是很不错的选择,博客园很多大佬,就swagger做了修改,以致于更加符合自己的需要,比如说有人给swagger加了生成pdf,word的功能,有人对swagger的权限控制做了管理,swagger有很大的人群在使用。
不过说到最后,我还是觉得apidoc 更符合国人的胃口。
初步快速搭建起项目
配置apidoc
- cli安装apidoc或通过nuget包管理器安装apidoc
dotnet add package aspnetcore.apidoc --version 2.2.0.3
- 配置configureservices
public void configureservices(iservicecollection services) { services.addapidoc(t => { t.apidocpath = "apidoc";//api访问路径 t.title = "爆点";//文档名称 }); ... }
- 配置完毕,就是这么easy
配置swagger
- 通过cli安装或通过nuget包管理器安装swagger
- 配置configureservices
public void configureservices(iservicecollection services) { services.addswaggergen(c => { c.swaggerdoc("v1", new info { title = "爆点api接口文档", version = "v1", contact = new contact { name = "鸟窝", email = "topbrids@gmail.com", url = "http://www.cnblogs.com/gdsblog" } }); c.includexmlcomments(xmlcommentsfilepath); c.includexmlcomments(xmldomiancommentsfilepath); }); ... }
- configure 里use一下
public void configure(iapplicationbuilder app, ihostingenvironment env) { app.useswagger(); app.useswaggerui(c => { c.swaggerendpoint("/swagger/v1/swagger.json", "爆点"); }); ... }
- ok swagger 配置完毕
提需求,描述接口业务
写一个获取广告图的接口
输入不同的入参可以获取不同位置的广告图
get/post请求
接口响应体,是一个list,可能有一条广告,也可能有多条广告
具体撸码实现该接口
- 接口展示
/// <summary> /// 获取广告/banner/公告 /// </summary> /// <param name="type"></param> /// <returns> /// <see cref="advertisingmodel" langword="true"/> /// </returns> [httpget] [allowanonymous] public responsresult getad(adlocation type) { return rpwservice.getads(type); }
该接口名称为getad,请求方式为get,advertisingmodel 是一个接口返回的关键数据对象模型,接口入参是一个枚举
responsresult是一个接口统一返回模型,下面具体展示器内容,[allowanonymous] 表示接口可以匿名访问,无需验证advertisingmodel 内容
public class advertisingmodel { /// <summary> /// 唯一id /// </summary> public string id { get; set; } /// <summary> /// 标题 /// </summary> public string adname { get; set; } /// <summary> /// 开始时间 /// </summary> public datetime? begintime { get; set; } /// <summary> /// 结束时间 /// </summary> public datetime? endtime { get; set; } /// <summary> /// 图片s /// </summary> public string adpic { get; set; } /// <summary> /// 描述 /// </summary> public string addesc { get; set; } /// <summary> /// 类型 /// </summary> public adlocation adlocation { get; set; } }
- adlocation 内容
public enum adlocation { /// <summary> /// 首页 /// </summary> [description("首页")] home = 1, /// <summary> /// 支付成功 /// </summary> [description("支付成功")] paysuccessful, /// <summary> /// 登录页 /// </summary> [description("登录页")] login, /// <summary> /// 公告 /// </summary> [description("公告")] gonggao, /// <summary> /// 启动页广告 /// </summary> [description("启动页")] splashpage, /// <summary> /// banner广告 /// </summary> [description("banner广告")] banner }
接下来对比一下apidoc和swagger的展示效果
apidoc
swagger
结论
大家只要仔细对比,同样的代码,apidoc和swagger对比的效果,宛如天堂和地狱,欢迎大家在项目中试用!
上一篇: Java解析Excel之POI(一)
下一篇: Java经典面试题+答案(全)