欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

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

程序员文章站 2022-08-26 10:02:38
[aspnetcore.apidoc]一款很不错的api文档生成工具 ......

aspnetcore.apidoc

[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

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

  1. 配置configureservices
public void configureservices(iservicecollection services)
        {
            services.addapidoc(t =>
            {
                t.apidocpath = "apidoc";//api访问路径
                t.title = "爆点";//文档名称
            });
            ...
        }

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

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

配置swagger

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

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

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

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

  1. configure 里use一下

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

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

        }

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

  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

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

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

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

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

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

swagger

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

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

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

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

结论

大家只要仔细对比,同样的代码,apidoc和swagger对比的效果,宛如天堂和地狱,欢迎大家在项目中试用!