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

 

若有問題,歡迎留言指教.