一 背景

随着前端技术的不断发展,各种框架逐渐成熟,前端 Angular,React,Vue 三分天下。再加上移动端的崛起,前后端分离开发成为主流,前端后端代码混合开发的方式沦为被淘汰的局面。如今 MVC 框架中的 View 已经名存实亡,大多数 Asp.Net Core 项目都只提供 Api 接口服务。在前后端分离开发过程中,Api接口成为了连接前后端的唯一桥梁。

所以沟通清楚Api接口成为了重中之重。Api接口文档就成为了必不可少的文件。

二 现状

现在有很多的第三方接口文档维护网站,比如Eolinker,EasyAPI等。第三方的API接口服务,接口大多需要手动录入,接口变动后需要手动修改。维护比较繁琐。.net里面的Api接口文档当然要提下Swagger了。Swagger兼具了Api文档管理和测试的功能。是一个比较成熟的API接口文档管理工具。

三 问题

既然已经有Swagger了为啥还要自己造轮子呢?介绍下我在使用过程中碰到的问题。因为我喜欢用Mvc项目模板,form表单格式可以满足大多数的需求。Swagger在webApi项目中可以正常使用,在Mvc模板中引入却不工作,无法生成接口文档。可能是哪配置的不对。拉下Swagger的源码调试下,打开Swagger的项目基本上蒙圈了。引入项目中调试跟入也没搞懂。一直没看懂是在哪生成的方法接口信息。

从直觉上来讲,生成文档的思路应该比较清晰,从程序集读取接口,类对象,属性相关信息,然后再通过解析xml说明文件就可以了。So自己造一个吧,造一个大家都能看懂的轮子。

四 使用技术

.Net Standard 类库项目 引入AspNetCore.Mvc.Core等相关nuget包

UI使用angular目前最新版本8.0,引入Ant Design 的NG-ZORRO框架。

五 JcApiHelper优势

1.使用简单,只要在startup中调用app.UseJcApiHelper()即可引入

2.可按controller浏览接口,支持接口筛选查找

3.支持项目非根目录部署和nginx代理

六 即将加入的功能

支持前端TypeScript类对象和请求服务代码生成

在线http请求接口测试

WebSocket连接测试

Json格式化工具

七 可能存在的问题

1.接口信息安全问题

如果不想在发布版本中暴露接口信息,可以只在测试环境时,IHost.IsDev中引入。在ASP.NET Core项目中可以通过环境变量来控制环境切换,详细介绍参照https://www.cnblogs.com/tdfblog/p/Environments-LaunchSettings-in-Asp-Net-Core.html

2.接口授权拦截问题

如果你的项目做了统一授权管理,请在权限处理Filter中允许匿名访问。

ApiHelper接口Controller和Action都带有AllowAnoumous特性。如在权限Filter中未忽略该特性,可能会导致Helper接口被拦截无法访问。

八 使用方法

1.项目需要开启Xml文档生成

2.项目中引入Jc.ApiHelper包

在Mvc/WebApi项目中,打开Nuget包管理,搜索Jc.ApiHelper,然后选择Jc.ApiHelper目前最新版本安装

JcApiHelper 简单好用的.Net ApiHelper-LMLPHP

3.启用JcApiHelper

在StartUp文件,Configure方法中,加入如下代码,至此,JcApiHelper即启用完成.

app.UseJcApiHelper();

4.浏览效果

运行项目,然后访问http://localhost:5000/ApiHelper.

点击现在开始或菜单上的ApiHelper进入接口浏览页面

 

点击接口名称,查看接口详情

临时在线Demo地址:http://beipiaohome.cn/ApiHelper (个人云主机,临时在线测试使用,建议自己下载Demo测试)

Demo源码:https://github.com/279328316/JcApiHelper

九  关于开源和后续功能开发工作

目前项目基本功能已有,项目从起初有想法至今有2个月时间.而且是在业余时间开发.后续功能会陆续添加.

项目功能基本完善后,会将主要源码添加到https://github.com/279328316/JcApiHelper中.

如有问题欢迎随时留言指教.

07-11 23:55