[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

1. cli安装apidoc或经过nuget包管理器安装apidoc

dotnet add package AspNetCore.ApiDoc --version 2.2.0.3

1. 配置ConfigureServices

public void ConfigureServices(IServiceCollection services)
        {
            services.AddApiDoc(t =>
            {
                t.ApiDocPath = "apidoc";//api访问路径
                t.Title = "爆点";//文档名称
            });
            ...
        }

1. 配置完毕，就是这么easy

配置swagger

1. 经过cli安装或经过nuget包管理器安装swagger

1. 配置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);
            });
            ...
        }

1. configure 里use一下

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. 接口展现

/// <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);

        }

1. 该接口名称为GetAd,请求方式为get，AdvertisingModel 是一个接口返回的关键数据对象模型，接口入参是一个枚举
   ResponsResult是一个接口统一返回模型，下面具体展现器内容,[AllowAnonymous] 表示接口能够匿名访问，无需验证

2. 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; }
    }

1. 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对比的效果，宛如天堂和地狱，欢迎你们在项目中试用！

github 统一开源地址