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

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