JcApiHelper 简单好用的.Net ApiHelper

一 背景

随着前端技术的不断发展，各类框架逐渐成熟，前端 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本身造一个吧，造一个你们都能看懂的轮子。

四 使用技术

JcApiHelper,支持.net Core 2.0+ 版本(说明.Net Core 3.0请使用1.0.13版本 .Net Core 2.0请使用1.0.12版本)

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

UI使用angular，引入Ant Design 的NG-ZORRO框架。

五 JcApiHelper优点

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

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

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

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

5.在线http请求接口测试

6.WebSocket链接测试

7.Json格式化工具,支持自Json数据转换为TypeScript对象.

六 可能存在的问题

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目前最新版本安装

3.启用JcApiHelper

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

app.UseJcApiHelper();

4.浏览效果

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

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

 

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

 

在线Demo地址:https://apihelper.jccore.cn

八  项目源码

.Net项目源码:https://github.com/279328316/JcApiHelper

前端项目源码:https://github.com/279328316/JcApiHelper.Html

 

若有问题,欢迎留言指教.