AspnetCore 2.0 自動API文件生成元件,支援protobuffer
關於
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