【開源】AspnetCore 2.0 自動API文檔生成組件，支持protobuffer

本文地址

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 = "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>

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 = "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文檔生成
        }
    }

其他工具

在tool目錄下提供了批量下載proto文件的工具apiprotoasnic.go，基於go編寫，源代碼很簡單，就是解析json，這里不再單獨的提供說明文檔。

約定

• 所有API的方法傳入參數必須從Body中讀取

版權

本項目采用 MIT 開源授權許可證