Build Status Version Status NetCore Status Platform Status top.996
API文档自动生成,用于对APP端的开发帮助文档生成,默认ProtoBuffer传输格式。
本项目并不是RESTful风格,是面向功能的API类型。APiDoc的作用是根据定义好的API接口和注释来自动生成给内部开发者提供的API对接文档。
Install-Package AspnetCoreApiDoc
官方描述:
Protocol buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data.
- Bugs: Issues
- Gitter: Gitter channel
NO.1
引用项目后,在Startup.cs中的ConfigureServices方法加入如下代码,进行服务注册:
//注册API文档服务 services.AddProtoMvc(op => { op.IsOpenDoc = true; // 开放文档访问 op.ApiOptions = new ApiOptions { //API文档访问的路由; 推荐和API地址访问保持一致 DocRouter = "/core/v1", ApiName = "样例API文档", APiVersion = "v1.0", Copyright = "Copyright©2018-2011 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
此方案已经过时,可以参考5.0的xml生成方案 给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地址访问保持一致 DocRouter = "/core/v1", ApiName = "样例API文档", APiVersion = "v1.0", Copyright = "Copyright©2018-2011 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/" }, } }; }); } // 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) { app.UseStatusCodePages() .UseApi(); //启用API文档生成 } }
在tool目录下提供了批量下载proto文件的工具apiprotoasnic.go,基于go编写,源代码很简单,就是解析json,这里不再单独的提供说明文档。
- 所有API的方法传入参数必须从Body中读取
- MIT License
- 996ICU License