歡迎光臨
每天分享高質量文章

[aspnetcore.apidoc]一款很不錯的api文件生成工具

簡單徐速一下為什麼選用了aspnetcore.apidoc 而沒有選用swagger

最初我們也有在試用swagger,但總是有些感覺,感覺有點不滿意,就但從api文件角度來說,從前後端文件溝通角度來講
apidoc的表現形式,要比swagger簡單的多,效果也要好很多。

不要和我說什麼swagger現在已經是一個標準了,其實swagger的坑很多,就單說列舉型別抓取上,就顯示的很無奈,下麵我會創建專案,寫一個接口,拿這個接口舉例,同時用apidoc和swagger展示其文件效果,對比一下孰優孰劣。

當然我這裡並沒有引戰的意識,大家選用swagger,也是很不錯的選擇,博客園很多大佬,就swagger做了修改,以致於更加符合自己的需要,比如說有人給swagger加了生成pdf,word的功能,有人對swagger的權限控製做了管理,swagger有很大的人群在使用。

不過說到最後,我還是覺得apidoc 更符合國人的胃口。

初步快速搭建起專案

配置apidoc

  1. cli安裝apidoc或通過nuget包管理器安裝apidoc

dotnet add package AspNetCore.ApiDoc –version 2.2.0.3

  1. 配置ConfigureServices
Copy

public void ConfigureServices(IServiceCollection services)
{
services.AddApiDoc(t =>
{
t.ApiDocPath = "apidoc";//api訪問路徑
t.Title = "爆點";//文件名稱
});
...
}

  1. 配置完畢,就是這麼easy

配置swagger

  1. 通過cli安裝或通過nuget包管理器安裝swagger

  1. 配置ConfigureServices
Copy

public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Title = "爆點API接口文件",
Version = "v1",
Contact = new Contact
{
Name = "鳥窩",
Email = "[email protected]",
Url = "http://www.cnblogs.com/gdsblog"
}
});
c.IncludeXmlComments(XmlCommentsFilePath);
c.IncludeXmlComments(XmlDomianCommentsFilePath);
});
...
}

  1. configure 里use一下

Copy

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "爆點");
});

...
}

  1. ok swagger 配置完畢

提需求,描述接口業務

  1. 寫一個獲取廣告圖的接口

  2. 輸入不同的入參可以獲取不同位置的廣告圖

  3. get/post請求

  4. 接口響應體,是一個list,可能有一條廣告,也可能有多條廣告

具體擼碼實現該接口

  1. 接口展示
Copy

///
/// 獲取廣告/banner/公告
///

///
///
///
///
[HttpGet]
[AllowAnonymous]
public ResponsResult GetAd(AdLocation type)
{
return RpwService.GetAds(type);

}

  1. 該接口名稱為GetAd,請求方式為get,AdvertisingModel 是一個接口傳回的關鍵資料物件模型,接口入參是一個列舉
    ResponsResult是一個接口統一傳回模型,下麵具體展示器內容,[AllowAnonymous] 表示接口可以匿名訪問,無需驗證

  2. AdvertisingModel 內容

Copy

public class AdvertisingModel
{
///
/// 唯一id
///

public string Id { get; set; }
///
/// 標題
///
public string AdName { get; set; }
///
/// 開始時間
///
public DateTime? BeginTime { get; set; }
///
/// 結束時間
///
public DateTime? EndTime { get; set; }
///
/// 圖片s
///
public string AdPic { get; set; }
///
/// 描述
///
public string AdDesc { get; set; }

///
/// 型別
///
public AdLocation AdLocation { get; set; }
}

  1. AdLocation 內容
Copy

public enum AdLocation
{
///
/// 首頁
///

[Description(“首頁”)]
Home = 1,
///
/// 支付成功
///
[Description(“支付成功”)]
PaySuccessful,
///
/// 登錄頁
///
[Description(“登錄頁”)]
Login,
///
/// 公告
///
[Description(“公告”)]
GongGao,
///
/// 啟動頁廣告
///
[Description(“啟動頁”)]
SplashPage,
///
/// banner廣告
///
[Description(“banner廣告”)]
Banner

}

接下來對比一下apidoc和swagger的展示效果

apidoc

  1.  

  1.  

  1.  

  1.  

  1.  

swagger

  1.  

  1.  

  1.  

  1.  

結論

大家只要仔細對比,同樣的代碼,apidoc和swagger對比的效果,宛如天堂和地獄,歡迎大家在專案中試用!

原文地址:https://www.cnblogs.com/gdsblog/p/10296815.html

赞(0)

分享創造快樂