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界面，
轉載請註明出處，本文鏈接：https://www.uj5u.com/net/49.html
標籤：.NET Core