[aspnetcore.apidoc]一款很不錯的api文檔生成工具 ...
AspNetCore.ApiDoc
簡單徐速一下為什麼選用了aspnetcore.apidoc 而沒有選用swagger
最初我們也有在試用swagger，但總是有些感覺，感覺有點不滿意，就但從api文檔角度來說，從前後端文檔溝通角度來講
apidoc的表現形式，要比swagger簡單的多，效果也要好很多。
不要和我說什麼swagger現在已經是一個標準了，其實swagger的坑很多，就單說枚舉類型抓取上，就顯示的很無奈，下麵我會創建項目，寫一個介面，拿這個介面舉例，同時用apidoc和swagger展示其文檔效果，對比一下孰優孰劣。
當然我這裡並沒有引戰的意識，大家選用swagger，也是很不錯的選擇，博客園很多大佬，就swagger做了修改，以致於更加符合自己的需要，比如說有人給swagger加了生成pdf，word的功能，有人對swagger的許可權控製做了管理，swagger有很大的人群在使用。
不過說到最後，我還是覺得apidoc 更符合國人的胃口。
初步快速搭建起項目
配置apidoc
- cli安裝apidoc或通過nuget包管理器安裝apidoc
dotnet add package AspNetCore.ApiDoc --version 2.2.0.3
- 配置ConfigureServices
public void ConfigureServices(IServiceCollection services)
{
services.AddApiDoc(t =>
{
t.ApiDocPath = "apidoc";//api訪問路徑
t.Title = "爆點";//文檔名稱
});
...
}
- 配置完畢，就是這麼easy
配置swagger
- 通過cli安裝或通過nuget包管理器安裝swagger
- 配置ConfigureServices
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);
});
...
}
- configure 里use一下
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "爆點");
});
...
}
- ok swagger 配置完畢
提需求，描述介面業務
寫一個獲取廣告圖的介面
輸入不同的入參可以獲取不同位置的廣告圖
get/post請求
介面響應體，是一個list，可能有一條廣告，也可能有多條廣告
具體擼碼實現該介面
- 介面展示
/// <summary>
/// 獲取廣告/banner/公告
/// </summary>
/// <param name="type"></param>
/// <returns>
/// <see cref="AdvertisingModel" langword="true"/>
/// </returns>
[HttpGet]
[AllowAnonymous]
public ResponsResult GetAd(AdLocation type)
{
return RpwService.GetAds(type);
}
該介面名稱為GetAd,請求方式為get，AdvertisingModel 是一個介面返回的關鍵數據對象模型，介面入參是一個枚舉
ResponsResult是一個介面統一返回模型，下麵具體展示器內容,[AllowAnonymous] 表示介面可以匿名訪問，無需驗證AdvertisingModel 內容
public class AdvertisingModel
{
/// <summary>
/// 唯一id
/// </summary>
public string Id { get; set; }
/// <summary>
/// 標題
/// </summary>
public string AdName { get; set; }
/// <summary>
/// 開始時間
/// </summary>
public DateTime? BeginTime { get; set; }
/// <summary>
/// 結束時間
/// </summary>
public DateTime? EndTime { get; set; }
/// <summary>
/// 圖片s
/// </summary>
public string AdPic { get; set; }
/// <summary>
/// 描述
/// </summary>
public string AdDesc { get; set; }
/// <summary>
/// 類型
/// </summary>
public AdLocation AdLocation { get; set; }
}
- AdLocation 內容
public enum AdLocation
{
/// <summary>
/// 首頁
/// </summary>
[Description("首頁")]
Home = 1,
/// <summary>
/// 支付成功
/// </summary>
[Description("支付成功")]
PaySuccessful,
/// <summary>
/// 登錄頁
/// </summary>
[Description("登錄頁")]
Login,
/// <summary>
/// 公告
/// </summary>
[Description("公告")]
GongGao,
/// <summary>
/// 啟動頁廣告
/// </summary>
[Description("啟動頁")]
SplashPage,
/// <summary>
/// banner廣告
/// </summary>
[Description("banner廣告")]
Banner
}
接下來對比一下apidoc和swagger的展示效果
apidoc
swagger
結論
大家只要仔細對比，同樣的代碼，apidoc和swagger對比的效果，宛如天堂和地獄，歡迎大家在項目中試用！
