关于

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