ABP中關於Swagger的一些設定

Abp 整合 Swagger 官方檔案, 請參考 Swagger Integration

AspNetCore 設定 Swagger, 請參考 Swashbuckle.AspNetCore

本文的專案環境是 AspNetCore 6.0 + Volo.Abp.Swashbuckle 6.0.2

Abp 中預設的基礎設定如下:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    var services = context.Services;
    services.AddAbpSwaggerGen(
        options =>
        {
            options.SwaggerDoc("v1", new OpenApiInfo { Title = "Test API", Version = "v1" });
            options.DocInclusionPredicate((docName, description) => true);
            options.CustomSchemaIds(type => type.FullName);
        }
    );
}

這樣的設定,很難滿足我們的需求,比如它預設顯示了 Abp 相關的 endpoints 和 schema, 沒有詳細的介面註釋等

隱藏 Abp 相關的 endpoints

Abp 官方檔案 提及了這個操作,程式碼如下

services.AddAbpSwaggerGen(
    options =>
    {
        options.HideAbpEndpoints();
    }
);

隱藏 Abp 相關的 schemas

這個在官網中沒有發現,搜尋到可以實現自定義的 ISchemaFilter
參考: Hide Endpoints And Schemas from Swagger / OpenAPI

public class HideAbpSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        context.SchemaRepository.Schemas.RemoveAll(item => item.Key.StartsWith("Volo."));
    }
}

//使用方法
services.AddAbpSwaggerGen(
    options =>
    {
        options.SchemaFilter<HideAbpSchemaFilter>();
    }
);

隱藏 Abp 預設生成的響應型別

Abp 預設生成了 400,401,403,404,500,501 相關的響應

通過 AbpAspNetCoreMvcModule 這個模組的原始碼,我們看到了它的預設實現如下:

Configure<AbpRemoteServiceApiDescriptionProviderOptions>(options =>
{
    var statusCodes = new List<int>
    {
        (int) HttpStatusCode.Forbidden,
        (int) HttpStatusCode.Unauthorized,
        (int) HttpStatusCode.BadRequest,
        (int) HttpStatusCode.NotFound,
        (int) HttpStatusCode.NotImplemented,
        (int) HttpStatusCode.InternalServerError
    };

    options.SupportedResponseTypes.AddIfNotContains(statusCodes.Select(statusCode => new ApiResponseType
    {
        Type = typeof(RemoteServiceErrorResponse),
        StatusCode = statusCode
    }));
});

那就很好解決了,我們只要把它給清除就行了,程式碼如下

Configure<AbpRemoteServiceApiDescriptionProviderOptions>(options =>
{
    options.SupportedResponseTypes.Clear();
});

介面註釋

這個簡單,只要包含專案的 XML 檔案註釋就行

var xmlFilename1 = "EOA.User.WebApi.xml";
var xmlFilename2 = "EOA.User.Application.xml";
var xmlFilename3 = "EOA.User.Application.Contracts.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename1));
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename2));
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename3));

別忘了開啟生成專案的檔案註釋(可以直接編輯.csproj 檔案)

<PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

修改 Schema 預設的時間格式

直接全域性修改 DateTime 型別的 Schema 設定即可,給個預設的 Example

options.MapType<DateTime>(() => new OpenApiSchema { Type = "string", Example = new Microsoft.OpenApi.Any.OpenApiString("2000-01-01 00:00:00") });

結束

本文也是實際記錄我發現的一點小問題, 這麼一頓操作下來是不是清爽多了