如何在.NET Core 5 Web API的Swagger OAS规范中添加自定义属性

Swashbuckle 生成的 OpenApi 文档对象自带 Extensions 字典属性，专门用于存储 x- 开头的自定义扩展字段，直接在 Apply 方法中操作该属性即可实现需求。

基础版实现（仅添加生产可用标识） #

直接修改 CustomModelDocumentFilter 类的 Apply 方法：

public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
    // 添加与info同级的自定义字段，布尔值用OpenApiBoolean类型封装
    swaggerDoc.Extensions.Add("x-acme-production-ready", new Microsoft.OpenApi.Any.OpenApiBoolean(false));
}

运行项目后生成的Swagger JSON就会自动携带该自定义字段，位置和要求的与info同级一致。

完整版实现（同时添加所有示例中的自定义字段） #

如果还需要添加示例里的 x-acme-api-commitments、x-acme-api-changelog 字段，参考以下代码：

public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
    // 1. 添加生产可用标识
    swaggerDoc.Extensions.Add("x-acme-production-ready", new Microsoft.OpenApi.Any.OpenApiBoolean(false));

    // 2. 添加API承诺字段
    var commitments = new Microsoft.OpenApi.Any.OpenApiObject
    {
        ["api-100"] = new Microsoft.OpenApi.Any.OpenApiString("We commit to providing a proper valid OpenAPI (swagger) specification file for each API change.....")
    };
    swaggerDoc.Extensions.Add("x-acme-api-commitments", commitments);

    // 3. 添加变更日志字段
    var changelog = new Microsoft.OpenApi.Any.OpenApiArray
    {
        new Microsoft.OpenApi.Any.OpenApiObject
        {
            ["version"] = new Microsoft.OpenApi.Any.OpenApiString("1.0.0"),
            ["changes"] = new Microsoft.OpenApi.Any.OpenApiString("Add GET /example")
        },
        new Microsoft.OpenApi.Any.OpenApiObject
        {
            ["version"] = new Microsoft.OpenApi.Any.OpenApiString("1.1.0"),
            ["changes"] = new Microsoft.OpenApi.Any.OpenApiString("Add POST /example")
        }
    };
    swaggerDoc.Extensions.Add("x-acme-api-changelog", changelog);
}

动态赋值方案（按环境切换生产可用状态） #

如果需要根据运行环境动态调整 x-acme-production-ready 的值，可以通过构造函数注入环境参数：

1. 修改Filter类，添加构造函数接收参数：

public class CustomModelDocumentFilter : IDocumentFilter
{
    private readonly bool _isProductionReady;
    public CustomModelDocumentFilter(bool isProductionReady)
    {
        _isProductionReady = isProductionReady;
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Extensions.Add("x-acme-production-ready", new Microsoft.OpenApi.Any.OpenApiBoolean(_isProductionReady));
    }
}

2. 在Startup中注册Filter时传入动态值：

services.AddSwaggerGen(c =>
{
    // 只有生产环境设置为true，其他环境都是false
    var isProd = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Production";
    c.DocumentFilter<CustomModelDocumentFilter>(isProd);
    // 其余原有配置保持不变
    c.SwaggerDoc("v1.0", new OpenApiInfo { Title = "my app title", Version = "v1.0", Description = "my app description." });
    // ...其余xml配置保持不变
});

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