API 文档自动生成,用于对 APP 端的开发帮助文档生成,默认 ProtoBuffer 传输格式。
本项目并不是 RESTful 风格,是面向功能的 API 类型。ApiDoc 的作用是根据定义好的 API 接口和注释来自动生成给内部开发者提供的 API 对接文档。
欢迎 Star 一下,后续还会更新配套的 SDK 自动生成,基于 Consul 的服务注册与发现等,当然,由于我本人能力有限,菜的很,所以这个工具若是对您有用,并且您有了新的点子,同样欢迎提交您的合并请求,我会认真阅读,并维护好项目。
- Install - Package AspnetCoreApiDoc
官方描述:
Protocol buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data.
引用项目后,在 Startup.cs 中的 ConfigureServices 方法加入如下代码,进行服务注册:
NO.2
- //注册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",
- //};
- });
在 Configure 方法启用服务:
NO.3
- app.UseStatusCodePages().UseApi(); //启用API文档生成
在需要生成 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文档生成
- }
- }
本项目采用 MIT 开源授权许可证
来源: https://www.cnblogs.com/likeli/p/8204054.html