Swagger這個優秀的開源項目相信大家都用過，不多介紹了，這里簡單記錄一下使用過程。

開源地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

在項目中添加組件

Install-Package Swashbuckle.AspNetCore

下面用最少的代碼完成接入，在Startup啟動項中配置。

public?void?ConfigureServices(IServiceCollection?services) {...services.AddSwaggerGen(x?=>{x.SwaggerDoc("v1",?new?Microsoft.OpenApi.Models.OpenApiInfo{Version?=?"v1.0.0",Title?=?"Api",Description?=?"XXX?Api"});});... } public?void?Configure(IApplicationBuilder?app,?IWebHostEnvironment?env) {...app.UseSwagger();app.UseSwaggerUI(c?=>{c.SwaggerEndpoint("/swagger/v1/swagger.json",?"API");});... }

這樣便完成了，swagger會自動發現我們在controller中寫的api，默認打開頁面為：~/swagger。

同時還可以讓其支持分組展示，只需要像上面一樣配置多個節點信息接口，如下面代碼：

services.AddSwaggerGen(options?=> {options.SwaggerDoc("v1",?new?Microsoft.OpenApi.Models.OpenApiInfo{Version?=?"v1.0.0",Title?=?"Api1",Description?=?"XXX?Api1"});options.SwaggerDoc("v2",?new?Microsoft.OpenApi.Models.OpenApiInfo{Version?=?"v1.0.0",Title?=?"Api2",Description?=?"XXX?Api2"}); }); app.UseSwaggerUI(c?=> {c.SwaggerEndpoint("/swagger/v1/swagger.json",?"API1");c.SwaggerEndpoint("/swagger/v2/swagger.json",?"API2"); });

如果在控制器中不指定接口的分組名稱，那么每個分組都會顯示這個接口，如果需要單獨指定可以使用特性[ApiExplorerSettings(GroupName = "v1")]這樣。

如果想要顯示接口的注釋，模型的注釋等信息，需要我們將對應的項目設置輸出XML文件，并在代碼中使用options.IncludeXmlComments(xxx.xml)即可。

下面來說一下swagger的一些其它功能，當我們接口開啟了JWT方式的認證，默認swagger是不支持的，需要我們手動去適配一下。

需要額外添加一個組件

Install-Package Swashbuckle.AspNetCore.Filters context.Services.AddSwaggerGen(options?=> {...var?security?=?new?OpenApiSecurityScheme{Description?=?"<b>please?enter?<code>Bearer?{Token}</code>?for?authentication.</b>",Name?=?"Authorization",In?=?ParameterLocation.Header,Type?=?SecuritySchemeType.ApiKey};options.AddSecurityDefinition("oauth2",?security);options.AddSecurityRequirement(new?OpenApiSecurityRequirement?{?{?security,?null?}?});options.OperationFilter<AddResponseHeadersFilter>();options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();options.OperationFilter<SecurityRequirementsOperationFilter>(); });

現在UI界面便會出現小綠鎖，這樣就可以很方便的在swagger上進行需要授權的接口調試工作了。

同時swagger還支持一些高級操作，比如自定義UI界面、注入JS、CSS代碼，因為這個用的不是很多，實際要用的時候可以去GitHub查看使用方法。

//?Customize?index.html app.UseSwaggerUI(c?=> {c.IndexStream?=?()?=>?GetType().Assembly.GetManifestResourceStream("CustomUIIndex.Swagger.index.html"); });//?Inject?Custom?CSS app.UseSwaggerUI(c?=> {...c.InjectStylesheet("/swagger-ui/custom.css"); }

這里還要說一下swagger的過濾器，我們可以實現IDocumentFilter接口，來實現自定義的接口排序，個性化接口描述，以及各種騷操作，比如我們想要隱藏某些API，當然隱藏API可以使用.NET Core 的特性[ApiExplorerSettings(IgnoreApi = true)]實現。

這里隱藏是指不在swaggerUI中顯示，實際接口還是存在的。

public?class?SwaggerDocumentFilter?:?IDocumentFilter {public?void?Apply(OpenApiDocument?swaggerDoc,?DocumentFilterContext?context){var?tags?=?new?List<OpenApiTag>{new?OpenApiTag?{Name?=?"Authentication",Description?=?"Authentication",ExternalDocs?=?new?OpenApiExternalDocs?{?Description?=?"Authentication"?}},new?OpenApiTag?{Name?=?"Localization",Description?=?"Localization",ExternalDocs?=?new?OpenApiExternalDocs?{?Description?=?"Localization"?}}};swaggerDoc.Tags?=?tags.OrderBy(x?=>?x.Name).ToList();var?apis?=?context.ApiDescriptions.Where(x?=>?x.RelativePath.Contains("abp"));if?(apis.Any()){foreach?(var?item?in?apis){swaggerDoc.Paths.Remove("/"?+?item.RelativePath);}}} }

上面這段代碼，使用了abp框架搭建的項目，abp默認實現了一部分接口，如果我們不需要的話就可以使用上面的方式進行過濾。

最后一點，如果我們用了第三方框架，像上面說的abp，或者使用了動態API生成的組件，比如：Plus.AutoApi，想要在swagger中顯示出api接口，需要添加下面這句代碼。

context.Services.AddSwaggerGen(options?=> {...options.DocInclusionPredicate((docName,?description)?=>?true);... });

swagger推出的同時還推出了一款工具ReDoc，下面也簡單介紹一下。

ReDoc和swagger比較類似，只是一個文檔展示工具，不提供接口調試的功能。

他們的使用方式基本一致，先在項目中添加一下組件

Install-Package Swashbuckle.AspNetCore.ReDoc

在OnApplicationInitialization中直接添加一句配置即可。

app.UseReDoc();

它支持多種參數選項，可以自行查看，默認打開頁面為：~/api-docs，下面是他的UI界面。

總結

以上是生活随笔為你收集整理的.NET Core API文档管理组件 Swagger的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。