【开源】AspnetCore 2.0 自动API文档生成组件,支持protobuffer_weixin_30532369的博客-程序员宅基地

技术标签: json  runtime  

本文地址

http://www.cnblogs.com/likeli/p/8204054.html

关于

API文档自动生成,用于对APP端的开发帮助文档生成,默认ProtoBuffer传输格式。

本项目并不是RESTful风格,是面向功能的API类型。APiDoc的作用是根据定义好的API接口和注释来自动生成给内部开发者提供的API对接文档。

有任何问题,请在github提Issues

开源地址

https://github.com/li-keli/AspnetCoreApiDoc

Nuget下载

Install-Package AspnetCoreApiDoc

关于ProtoBuffer

官方描述:

Protocol buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data.

生成文档示例

示例文档

线上文档更新后立即提示

线上文档更新后立即提示

说明文档

NO.1

引用项目后,在Startup.cs中的ConfigureServices方法加入如下代码,进行服务注册:

    //注册API文档服务
    services.AddProtoMvc(op =>
    {
        op.IsOpenDoc = true; // 开放文档访问
        op.ApiOptions = new ApiOptions
        {
            //API文档访问的路由; 推荐和API地址访问保持一致
            Host = "/core/v1",
            ApiName = "样例API文档",
            APiVersion = "v1.0",
            Copyright = "Copyright2017-2018 api.com All Rights Reserved. ",
            ProtoBufVersion = ProtoBufEnum.Proto3,
            NetworkDocs = new List<NetworkDoc>
            {
                new NetworkDoc
                {
                    Title = "默认网络文档一",
                    Url = "https://www.baidu.com/"
                },
                new NetworkDoc
                {
                    Title = "我的博客",
                    Url = "http://www.cnblogs.com/likeli/"
                },
            }
        };
        //此处配置ES日志服务地址
        //op.ESOptions = new ESOptions
        //{
        //    Uri = "http://192.168.0.1:9200",
        //    DefaultIndex = "test-log",
        //};
    });

NO.2

Configure方法启用服务:

    app.UseStatusCodePages()
        .UseApi();  //启用API文档生成

NO.3

在需要生成API文档的控制器Controller``或方法Action上添加ApiDoc特性标记

例如:

Controller上添加:

    [ApiDoc, Route("core/v1/[controller]/[action]/")]
    public class ApiController
    {
        ...
    }

Action上添加:

    /// <summary>
    /// 获取产品方法2
    /// </summary>
    /// <param name="input">输入参数</param>
    /// <returns>输出参数</returns>
    [ApiDoc, HttpPost]
    public ProductInput GetProduct2([FromBody] ProductInput input)
    {
        return new ProductInput {ProductName = "一体机"};
    }

在controller上添加ApiDoc特性后,可以在该控制器下的action上再添加ApiDoc(false)来停止某个单独方法的文档生成

NO.4

给API的项目和所有其依赖的项目的.csproj文件中的Project节点下都加上生成XML的配置,如下:

  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <DocumentationFile>bin\Debug\netcoreapp2.0\{项目名}.xml</DocumentationFile>
    <DocumentationFile>bin\Release\netcoreapp2.0\{项目名}.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

NO.5

通过游览器打开http://localhost:5000/core/v1/api.do来访问API文档

完整实例:

    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }
    
        public IConfiguration Configuration { get; }
    
        public void ConfigureServices(IServiceCollection services)
        {
            //加载日志记录组件
            services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
            services.AddSingleton<ESClientProvider>();
    
            //注册API文档服务
            services.AddProtoMvc(op =>
            {
                op.IsOpenDoc = true; // 开放文档访问
                op.ApiOptions = new ApiOptions
                {
                    //API文档访问的路由; 推荐和API地址访问保持一致
                    Host = "/core/v1",
                    ApiName = "样例API文档",
                    APiVersion = "v1.0",
                    Copyright = "Copyright2017-2018 api.com All Rights Reserved. ",
                    ProtoBufVersion = ProtoBufEnum.Proto3,
                    NetworkDocs = new List<NetworkDoc>
                    {
                        new NetworkDoc
                        {
                            Title = "默认网络文档一",
                            Url = "https://www.baidu.com/"
                        },
                        new NetworkDoc
                        {
                            Title = "我的博客",
                            Url = "http://www.cnblogs.com/likeli/"
                        },
                    }
                };
                //此处配置ES日志服务地址
                //op.ESOptions = new ESOptions
                //{
                //    Uri = "http://192.168.0.1:9200",
                //    DefaultIndex = "test-log",
                //};
            });
        }
    
        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
        {
            //启动ES日志服务
            //loggerFactory
            //    .AddESLogger(app.ApplicationServices, "test-log", new FilterLoggerSettings
            //    {
            //        {"*", LogLevel.Trace},
            //        {"Microsoft", LogLevel.Warning},
            //        {"System", LogLevel.Warning},
            //    });
            app.UseStatusCodePages()
                .UseApi(); //启用API文档生成
        }
    }

其他工具

在tool目录下提供了批量下载proto文件的工具apiprotoasnic.go,基于go编写,源代码很简单,就是解析json,这里不再单独的提供说明文档。

约定

  • 所有API的方法传入参数必须从Body中读取

版权

本项目采用 MIT 开源授权许可证

转载于:https://www.cnblogs.com/likeli/p/8204054.html

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/weixin_30532369/article/details/95665323

智能推荐

Java Math类 四舍五入_JayceHarris的博客-程序员宅基地_java math四舍五入

四舍五入保留两位return(double)Math.round(number * 100)/ 100;基本用法public static long round(double a):返回最接近参数的long类型值(long) public static int round(float a):返回最接近参数的int类型值(int) long d1 = Math.round(5.5); // 6l long d2 = Math.round(5.4); // 5

广州医科大学大一计算机课程表,广州医科大学2014-2015-2学期2014级预防医学专业本科课程表(正稿)..._奉义天涯的博客-程序员宅基地

广州医科大学2014-2015-2学期 2014级预防医学专业本科课程表(正稿)第1周 2015.3.9-3.13 二 10/3 三 11/3 计算机基础与 应用(2) 公共英语 (2) 医学细胞生物学节次1(08:30-09:10) 2(09:20-10:00) 3(10:10-10:50) 4(11:00-11:40) 5(11:50-12:30) 6(14:00-14:40) 7(14:50...

iOS开发打字机效果_小小龙包的博客-程序员宅基地_iapp打字机特效代码

iOS开发打字机效果效果展示下载链接效果展示实现了一个打字机效果,可以切分文字后逐渐跳出,能自动居中和自动换行。下载链接https://download.csdn.net/download/qq_29137557/12474766

A+B+C  Gym - 101917G JAVA_董公子的博客-程序员宅基地

A - A+B+CGym - 101917GA,B,C三个有理数写成分子分母为整数的分数的形式,请你计算A+B+C.Input输入共T+1行,第一行有一个整数T代表共有T组数据。接下来有T行,每行有3个分数由空格隔开,每个分数的形式都是n/d,n与d均为正整数。1 ≤ T ≤ 103 1 ≤ n,d ≤ 106Output输出T行,每行输出一个分数,等于对应行的三个...

手绘与码绘的对比 静态绘画_WWWWWsj的博客-程序员宅基地

手绘 码绘  代码第一次使用Processing 用到的都是最简单基础的函数//先设一个全黑的背景void setup() { size(900,300); background(0);}void draw() { ellipseMode(CENTER); rectMode(CENTER); noStroke(); // ...

SQL CTE 递归游戏-你厉害吗,来过5关_吃着泡面写点CODE的博客-程序员宅基地

转载SQL大牛的文章,CTE技术用于递归查询真是挺好用的,我也是刚接触这个。附CTE百度百科:http://baike.baidu.com/view/1013815.htm 转载地址:http://blog.csdn.net/jinjazz/article/detai

随便推点

sencha touch2 自定义样式(theme)_lihongxun945的博客-程序员宅基地

在上一篇中提过,sencha touch使用的是sass来写css,用compass打包压缩。用户自己编写的样式文件,默认的入口是resources/sass/app.sass。关于sass文件的组织,如果是比较简单的项目,一个app.scss就足够了,如果是比较大的项目,可以把app.scss当做入口文件,里面引入其他的scss模块即可。默认的主题是default theme,路径是

Objective-C中的block块语法_weixin_30758821的博客-程序员宅基地

#import &lt;Foundation/Foundation.h&gt; /* OC不同于Java C++ 它没有字符串对象 只有NS对象 NS就是乔布斯第一个公司NeXt的类集合 被收购之后才有了CG类集合 统一合并到Foundation框架 以及后来的Cocoa框架 QuartZ Cocoas-2d 3d框架... 一般来说 ObjC中的类不是NS就...

java 将json转换成sql_SQL Server中将查询结果转换为Json格式脚本分享_迟趣的博客-程序员宅基地

脚本源码:SET ANSI_NULLS ONGOSET QUOTED_IDENTIFIER ONGOCREATE PROCEDURE[dbo].[SerializeJSON](@ParameterSQL AS VARCHAR(MAX))ASBEGINDECLARE @SQL NVARCHAR(MAX)DECLARE @XMLString VARCHAR(MAX)DECLARE @XML XMLDE...

Qt中plugin cannot be loaded for module ” “的解决办法_Richard的苹果的博客-程序员宅基地

Qt中plugin cannot be loaded for module ” “的解决办法plugin cannot be loaded for module “QtQuick.XmlListModel”: ???D:\qt5.9\5.9\mingw53_32\qml\QtQuick\XmlListModel\qmlxmllistmodelplugind.dll???C:\Users\user\Desktop\new\build-General-Desktop_Qt_5_9_0_MinGW_32

5分钟了解Java 12 八大新特性_高可用架构的博客-程序员宅基地

导读:Java 12 终于发布了,我们一起来看一看 Java 12 中的新特性。通过本文可以在5分钟内快速了解 Java 12 新特性。1 Switch 表达式使用Jav...

mysql 性能优化(七)锁机制_CodingAnHour的博客-程序员宅基地_mysql锁优化

解决因资源共享,而造成的并发问题。例如:例如:电商A,B两人同时购买最后一件商品A:仅快0.0001秒抢到的-&gt;加锁-&gt;处理业务逻辑-&gt;释放锁B:在B获取到商品时,商品已加锁,等待所释放,商品状态已发生改变,已售空。分类:操作类型:读锁(共享锁):对同一个数据,可以同时进行多个读操作,互不干扰写锁(互斥锁): 如果当前写操作没有完成(未释放锁),则无法进行其他的读操作和写操作操作范围:行锁表锁页锁...

推荐文章

热门文章

相关标签