關(guān)于

API文檔自動生成，用于對APP端的開發(fā)幫助文檔生成，默認ProtoBuffer傳輸格式。

本項目并不是RESTful風格，是面向功能的API類型。ApiDoc的作用是根據(jù)定義好的API接口和注釋來自動生成給內(nèi)部開發(fā)者提供的API對接文檔。

歡迎Star一下，后續(xù)還會更新配套的SDK自動生成，基于Consul的服務(wù)注冊與發(fā)現(xiàn)等，當然，由于我本人能力有限，菜的很，所以這個工具若是對您有用，并且您有了新的點子，同樣歡迎提交您的合并請求，我會認真閱讀，并維護好項目。

開源地址

https://github.com/CBDlkl/AspnetCoreApiDoc

Nuget下載

Install-Package AspnetCoreApiDoc

關(guān)于ProtoBuffer

官方描述：

Protocol buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data.

生成文檔示例

說明文檔

NO.1
引用項目后，在Startup.cs中的ConfigureServices方法加入如下代碼，進行服務(wù)注冊：

? ?//注冊API文檔服務(wù)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 = "默認網(wǎng)絡(luò)文檔一",Url = "https://www.baidu.com/"}, ? ? ? ? ? ? ? ?new NetworkDoc{Title = "我的博客",Url = "http://www.cnblogs.com/likeli/"},}}; ? ? ? ?//此處配置ES日志服務(wù)地址//op.ESOptions = new ESOptions//{// ? ?Uri = "http://192.168.0.1:9200",// ? ?DefaultIndex = "test-log",//};});

NO.2
在Configure方法啟用服務(wù)：

? ?app.UseStatusCodePages().UseApi(); ?//啟用API文檔生成

NO.3
在需要生成API文檔的控制器Controller``或方法Action上添加ApiDoc特性標記

例如：

Controller上添加：

? ?[ApiDoc, Route("core/v1/[controller]/[action]/")] ? ?public class ApiController{...}

Action上添加：

? ?/// <summary>/// 獲取產(chǎn)品方法2/// </summary>/// <param name="input">輸入?yún)?shù)</param>/// <returns>輸出參數(shù)</returns>[ApiDoc, HttpPost] ? ?public ProductInput GetProduct2([FromBody] ProductInput input) ? ?{ ? ? ? ?return new ProductInput {ProductName = "一體機"};}

在controller上添加ApiDoc特性后，可以在該控制器下的action上再添加ApiDoc(false)來停止某個單獨方法的文檔生成

NO.4
給API的項目和所有其依賴的項目的.csproj文件中的Project節(jié)點下都加上生成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文檔服務(wù)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 = "默認網(wǎng)絡(luò)文檔一",Url = "https://www.baidu.com/"}, ? ? ? ? ? ? ? ? ? ? ? ?new NetworkDoc{Title = "我的博客",Url = "http://www.cnblogs.com/likeli/"},}}; ? ? ? ? ? ? ? ?
? ?? ?//此處配置ES日志服務(wù)地址//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日志服務(wù)//loggerFactory// ? ?.AddESLogger(app.ApplicationServices, "test-log", new FilterLoggerSettings// ? ?{// ? ? ? ?{"*", LogLevel.Trace},// ? ? ? ?{"Microsoft", LogLevel.Warning},// ? ? ? ?{"System", LogLevel.Warning},// ? ?});app.UseStatusCodePages().UseApi(); //啟用API文檔生成}}

約定

• 所有API的方法傳入?yún)?shù)必須從Body中讀取

版權(quán)

本項目采用 MIT 開源授權(quán)許可證

原文地址:?https://www.cnblogs.com/likeli/p/8204054.html

---

.NET社區(qū)新聞，深度好文，歡迎訪問公眾號文章匯總 http://www.csharpkit.com

總結(jié)

以上是生活随笔為你收集整理的AspnetCore 2.0 自动API文档生成组件，支持protobuffer的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。