簡(jiǎn)單徐速一下為什么選用了aspnetcore.apidoc 而沒有選用swagger

最初我們也有在試用swagger，但總是有些感覺，感覺有點(diǎn)不滿意，就但從api文檔角度來說，從前后端文檔溝通角度來講
apidoc的表現(xiàn)形式，要比swagger簡(jiǎn)單的多，效果也要好很多。

不要和我說什么swagger現(xiàn)在已經(jīng)是一個(gè)標(biāo)準(zhǔn)了，其實(shí)swagger的坑很多，就單說枚舉類型抓取上，就顯示的很無奈，下面我會(huì)創(chuàng)建項(xiàng)目，寫一個(gè)接口，拿這個(gè)接口舉例，同時(shí)用apidoc和swagger展示其文檔效果，對(duì)比一下孰優(yōu)孰劣。

當(dāng)然我這里并沒有引戰(zhàn)的意識(shí)，大家選用swagger，也是很不錯(cuò)的選擇，博客園很多大佬，就swagger做了修改，以致于更加符合自己的需要，比如說有人給swagger加了生成pdf，word的功能，有人對(duì)swagger的權(quán)限控制做了管理，swagger有很大的人群在使用。

不過說到最后，我還是覺得apidoc 更符合國(guó)人的胃口。

初步快速搭建起項(xiàng)目

配置apidoc

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

dotnet add package AspNetCore.ApiDoc --version 2.2.0.3

配置ConfigureServices

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

配置完畢，就是這么easy

配置swagger

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

配置ConfigureServices

Copypublic void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Title = "爆點(diǎn)API接口文檔",
Version = "v1",
Contact = new Contact
{
Name = "鳥窩",
Email = "topbrids@gmail.com",
Url = "http://www.cnblogs.com/gdsblog"
}
});
c.IncludeXmlComments(XmlCommentsFilePath);
c.IncludeXmlComments(XmlDomianCommentsFilePath);
});
...
}

configure 里use一下

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

...
}

ok swagger 配置完畢

提需求，描述接口業(yè)務(wù)

寫一個(gè)獲取廣告圖的接口

輸入不同的入?yún)⒖梢垣@取不同位置的廣告圖

get/post請(qǐng)求

接口響應(yīng)體，是一個(gè)list，可能有一條廣告，也可能有多條廣告

具體擼碼實(shí)現(xiàn)該接口

接口展示

Copy/// <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,請(qǐng)求方式為get，AdvertisingModel 是一個(gè)接口返回的關(guān)鍵數(shù)據(jù)對(duì)象模型，接口入?yún)⑹且粋€(gè)枚舉
ResponsResult是一個(gè)接口統(tǒng)一返回模型，下面具體展示器內(nèi)容,[AllowAnonymous] 表示接口可以匿名訪問，無需驗(yàn)證

AdvertisingModel 內(nèi)容

Copypublic class AdvertisingModel
{
/// <summary>
/// 唯一id
/// </summary>
public string Id { get; set; }
/// <summary>
/// 標(biāo)題
/// </summary>
public string AdName { get; set; }
/// <summary>
/// 開始時(shí)間
/// </summary>
public DateTime? BeginTime { get; set; }
/// <summary>
/// 結(jié)束時(shí)間
/// </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 內(nèi)容

Copypublic enum AdLocation
{
/// <summary>
/// 首頁
/// </summary>
[Description("首頁")]
Home = 1,
/// <summary>
/// 支付成功
/// </summary>
[Description("支付成功")]
PaySuccessful,
/// <summary>
/// 登錄頁
/// </summary>
[Description("登錄頁")]
Login,
/// <summary>
/// 公告
/// </summary>
[Description("公告")]
GongGao,
/// <summary>
/// 啟動(dòng)頁廣告
/// </summary>
[Description("啟動(dòng)頁")]
SplashPage,
/// <summary>
/// banner廣告
/// </summary>
[Description("banner廣告")]
Banner

}

接下來對(duì)比一下apidoc和swagger的展示效果

apidoc

swagger

結(jié)論

大家只要仔細(xì)對(duì)比，同樣的代碼，apidoc和swagger對(duì)比的效果，宛如天堂和地獄，歡迎大家在項(xiàng)目中試用！

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

.NET社區(qū)新聞，深度好文，歡迎訪問公眾號(hào)文章匯總 http://www.csharpkit.com

總結(jié)

以上是生活随笔為你收集整理的[aspnetcore.apidoc]一款很不错的api文档生成工具的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。