您的位置:首页 > 编程语言 > ASP

AspnetCore 2.0 自动API文档生成组件,支持protobuffer

2018-01-07 00:00 609 查看

关于

API文档自动生成,用于对APP端的开发帮助文档生成,默认
ProtoBuffer
传输格式。本项目并不是
RESTful
风格,是面向功能的API类型。ApiDoc的作用是根据定义好的API接口和注释来自动生成给内部开发者提供的API对接文档。欢迎
Star
一下,后续还会更新配套的SDK自动生成,基于Consul的服务注册与发现等,当然,由于我本人能力有限,菜的很,所以这个工具若是对您有用,并且您有了新的点子,同样欢迎提交您的合并请求,我会认真阅读,并维护好项目。

开源地址

https://github.com/CBDlkl/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.ApiOptions = new ApiOptions
       {            //API文档访问的路由; 推荐和API地址访问保持一致
           Host = "/core/v1",
           ApiName = "样例API文档",
           APiVersion = "v1.0",
           Copyright = "Copyright©2017-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>
完整实例:
   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.ApiOptions = new ApiOptions
               {
               //API文档访问的路由; 推荐和API地址访问保持一致
                   Host = "/core/v1",
                   ApiName = "样例API文档",
                   APiVersion = "v1.0",
                   Copyright = "Copyright©2017-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文档生成
       }
   }

约定

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

版权

本项目采用 MIT 开源授权许可证原文地址: https://www.cnblogs.com/likeli/p/8204054.html
.NET社区新闻,深度好文,欢迎访问公众号文章汇总 http://www.csharpkit.com 

内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签: 
相关文章推荐