Swagger中同名不同命名空间类的响应定义区分方法求助

这个问题我之前在项目里也踩过坑！Swagger默认会用类的简单名称作为Schema的键，所以不同命名空间下的同名类会被覆盖，只保留最后处理的那个，导致接口文档无法准确区分两种响应结构。下面分享几种不同技术栈下的解决方案：

.NET (Swashbuckle) #

如果你用的是Swashbuckle.AspNetCore（.NET Core/.NET 5+），可以通过自定义Schema过滤器来修改生成的Schema名称，把命名空间标识加进去：

1. 创建一个自定义过滤器类：

public class NamespaceSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 给Schema名称加上命名空间的后缀（取命名空间最后一段）
        var namespaceParts = context.Type.Namespace?.Split('.');
        if (namespaceParts != null && namespaceParts.Length > 0)
        {
            schema.Title = $"{namespaceParts.Last()}_{context.Type.Name}";
            // 更新Schema仓库中的键值对，避免覆盖
            context.SchemaRepository.Schemas.Remove(context.Type.Name);
            context.SchemaRepository.Schemas[schema.Title] = schema;
        }
    }
}

2. 在Startup/Program.cs中注册这个过滤器：

builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<NamespaceSchemaFilter>();
});

这样生成的Schema就会变成foo_Profile和bar_Profile，对应的接口响应引用也会自动指向正确的Schema。

Java (SpringDoc/Springfox) #

对于Java生态，比如用SpringDoc OpenAPI（推荐替代Springfox），可以通过自定义SchemaNameGenerator来重命名Schema：

1. 实现自定义的名称生成器：

import org.springdoc.core.customizers.SchemaNameGenerator;
import java.lang.reflect.Type;

public class NamespaceSchemaNameGenerator implements SchemaNameGenerator {
    @Override
    public String generate(Type type) {
        if (type instanceof Class) {
            Class<?> clazz = (Class<?>) type;
            // 用包名最后一段+类名作为Schema名称
            String packageName = clazz.getPackageName();
            String packageSuffix = packageName.substring(packageName.lastIndexOf('.') + 1);
            return packageSuffix + "_" + clazz.getSimpleName();
        }
        return SchemaNameGenerator.super.generate(type);
    }
}

2. 在配置类中注册：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public SchemaNameGenerator schemaNameGenerator() {
        return new NamespaceSchemaNameGenerator();
    }
}

生成的Schema会自动区分foo_Profile和bar_Profile，接口响应的引用也会对应正确的定义。

通用方案（手动指定Schema名称） #

如果只是少数几个同名类需要处理，直接在类上通过Swagger注解手动指定Schema名称更直接：

.NET #

在foo.Profile上：

[SwaggerSchema(Title = "FooProfile")]
public class Profile { ... }

在bar.Profile上：

[SwaggerSchema(Title = "BarProfile")]
public class Profile { ... }

Java #

在foo.Profile上：

@Schema(name = "FooProfile")
public class Profile { ... }

在bar.Profile上：

@Schema(name = "BarProfile")
public class Profile { ... }

修改Schema名称后，大部分Swagger实现都会自动更新接口响应的引用，不需要额外调整接口配置。

内容的提问来源于stack exchange，提问作者Steve