.NET Core API文檔管理組件 Swagger

Swagger這個(gè)優(yōu)秀的開源項(xiàng)目相信大家都用過，不多介紹了，這里簡單記錄一下使用過程。

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

在項(xiàng)目中添加組件

Install-Package Swashbuckle.AspNetCore

下面用最少的代碼完成接入，在Startup啟動(dòng)項(xiàng)中配置。

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會(huì)自動(dòng)發(fā)現(xiàn)我們在controller中寫的api，默認(rèn)打開頁面為：~/swagger。

同時(shí)還可以讓其支持分組展示，只需要像上面一樣配置多個(gè)節(jié)點(diǎn)信息接口，如下面代碼：

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");
});

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

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

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

需要額外添加一個(gè)組件

Install-Package Swashbuckle.AspNetCore.Filters

context.Services.AddSwaggerGen(options?=>
{
????...

????var?security?=?new?OpenApiSecurityScheme
????{
????????Description?=?"please?enter?Bearer?{Token}?for?authentication.",
????????Name?=?"Authorization",
????????In?=?ParameterLocation.Header,
????????Type?=?SecuritySchemeType.ApiKey
????};

????options.AddSecurityDefinition("oauth2",?security);
????options.AddSecurityRequirement(new?OpenApiSecurityRequirement?{?{?security,?null?}?});
????options.OperationFilter();
????options.OperationFilter();
????options.OperationFilter();
});

現(xiàn)在UI界面便會(huì)出現(xiàn)小綠鎖，這樣就可以很方便的在swagger上進(jìn)行需要授權(quán)的接口調(diào)試工作了。

同時(shí)swagger還支持一些高級操作，比如自定義UI界面、注入JS、CSS代碼，因?yàn)檫@個(gè)用的不是很多，實(shí)際要用的時(shí)候可以去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的過濾器，我們可以實(shí)現(xiàn)IDocumentFilter接口，來實(shí)現(xiàn)自定義的接口排序，個(gè)性化接口描述，以及各種騷操作，比如我們想要隱藏某些API，當(dāng)然隱藏API可以使用.NET Core 的特性[ApiExplorerSettings(IgnoreApi = true)]實(shí)現(xiàn)。

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

public?class?SwaggerDocumentFilter?:?IDocumentFilter
{
????public?void?Apply(OpenApiDocument?swaggerDoc,?DocumentFilterContext?context)
????{
????????var?tags?=?new?List
????????{
????????????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框架搭建的項(xiàng)目，abp默認(rèn)實(shí)現(xiàn)了一部分接口，如果我們不需要的話就可以使用上面的方式進(jìn)行過濾。

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

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

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

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

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

Install-Package Swashbuckle.AspNetCore.ReDoc

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

app.UseReDoc();

它支持多種參數(shù)選項(xiàng)，可以自行查看，默認(rèn)打開頁面為：~/api-docs，下面是他的UI界面。