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

時間 2019-11-29

標籤 aspnetcore.apidoc aspnetcore apidoc 一款不錯 api 文檔生成工具简体版

原文原文鏈接

AspNetCore.ApiDoc

簡單徐速一下爲何選用了aspnetcore.apidoc 而沒有選用swagger

最初咱們也有在試用swagger，但老是有些感受，感受有點不滿意，就但從api文檔角度來講，從先後端文檔溝通角度來說
apidoc的表現形式，要比swagger簡單的多，效果也要好不少。git

不要和我說什麼swagger如今已是一個標準了，其實swagger的坑不少，就單說枚舉類型抓取上，就顯示的很無奈，下面我會建立項目，寫一個接口，拿這個接口舉例，同時用apidoc和swagger展現其文檔效果，對比一下孰優孰劣。github

固然我這裏並無引戰的意識，你們選用swagger，也是很不錯的選擇，博客園不少大佬，就swagger作了修改，以至於更加符合本身的須要，好比說有人給swagger加了生成pdf，word的功能，有人對swagger的權限控制作了管理，swagger有很大的人羣在使用。json

不過說到最後，我仍是以爲apidoc 更符合國人的胃口。後端

初步快速搭建起項目

配置apidoc

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

dotnet add package AspNetCore.ApiDoc --version 2.2.0.3api

配置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 = "topbrids@gmail.com",
                        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 配置完畢

提需求，描述接口業務

寫一個獲取廣告圖的接口app
輸入不一樣的入參能夠獲取不一樣位置的廣告圖post
get/post請求ui
接口響應體，是一個list，可能有一條廣告，也可能有多條廣告3d

具體擼碼實現該接口

接口展現

/// <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] 表示接口能夠匿名訪問，無需驗證code
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

    }