ABP中关于Swagger的一些配置

Abp 集成 Swagger 官方文档, 请参考 Swagger Integration
AspNetCore 配置 Swagger, 请参考 Swashbuckle.AspNetCore
本文的项目环境是 AspNetCore 6.0 + Volo.Abp.Swashbuckle 6.0.2

Abp 中默认的基础配置如下:

C# 复制代码
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 官方文档 提及了这个操作,代码如下

C# 复制代码
services.AddAbpSwaggerGen(
    options =>
    {
        options.HideAbpEndpoints();
    }
);

隐藏 Abp 相关的 schemas

这个在官网中没有发现,搜索到可以实现自定义的 ISchemaFilter

参考: Hide Endpoints And Schemas from Swagger / OpenAPI

C# 复制代码
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 这个模块的源码,我们看到了它的默认实现如下:
C# 复制代码
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
    }));
});

那就很好解决了,我们只要把它给清除就行了,代码如下

C# 复制代码
Configure<AbpRemoteServiceApiDescriptionProviderOptions>(options =>
{
    options.SupportedResponseTypes.Clear();
});

接口注释

这个简单,只要包含项目的 XML 文档注释就行

C# 复制代码
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

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

结束

本文也是实际记录我发现的一点小问题, 这么一顿操作下来是不是清爽多了

相关推荐
小趴菜不能喝12 小时前
spring boot 3.x 整合Swagger3
java·spring boot·swagger
黑金IT2 天前
Fastify Swagger:自动化API文档生成与展示
nodejs·swagger·fastify
Crazy Struggle7 天前
.NET 平台 WPF 通用权限开发框架 (ABP)
.net·wpf·abp·通用权限管理
gc_22998 天前
Admin.NET源码学习(5:swagger使用浅析)
swagger·admin.net
tianxingzhe3716 天前
使用Radzen Blazor组件库开发的基于ABP框架炫酷UI主题
ui·blazor·abp·.net blazor·radzen blazor
李少兄1 个月前
解决Swagger 3中`Unable to scan documentation context default`错误
java·swagger
光影少年1 个月前
node配置swagger
前端·javascript·node.js·swagger
弥琉撒到我1 个月前
微服务swagger解析部署使用全流程
java·微服务·架构·swagger
Java小卷1 个月前
自研API接口管理工具APIFirst1.0版本介绍
api·swagger
yicj1 个月前
SpringBoot3 Swagger笔记整理
java·springboot·swagger