使用 Swashbuckle Asp.Net Core for ReDoc 添加 x-logo 供应商扩展答案

【问题标题】：Adding x-logo vendor extension using Swashbuckle Asp.Net Core for ReDoc使用 Swashbuckle Asp.Net Core for ReDoc 添加 x-logo 供应商扩展
【发布时间】：2019-06-17 12:48:28
【问题描述】：

我正在为 ReDoc 使用 swagger.json 文件（由 Swashbuckle 生成）来显示 API 文档。

我需要什么： 将x-logo 供应商扩展添加到使用 Swashbuckle（Swashbuckle.AspNetCore.SwaggerGen 库）生成的 swagger json 中，以便 ReDoc UI 在左上角显示徽标like this

问题： 我能够将x-log 添加到 swagger.json 文件，但它被添加到文件的错误部分。它需要在 info 部分内。

这就是我添加x-logo所做的工作

创建了一个像下面这样的文档过滤器

    public class XLogoDocumentFilter : IDocumentFilter
        {
            public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
            {
              swaggerDoc.Extensions["x-logo"] = new { url = "https://URL/of/the/logo", altText = "Company Logo" };
            }

        }

将过滤器添加到SwaggerDoc

services.AddSwaggerGen(options => 
{   
  options.DocumentFilter<XLogoDocumentFilter>();

});

实际

    {
      "swagger": "2.0",
      "info": {
        "version": "v1",
        "title":"Sample REST API"
      },
      "x-logo": {
        "url": "https://rebilly.github.io/ReDoc/petstore-logo.png",
        "altText": "Aimia Logo"
      }
    }

预期

    {
      "swagger": "2.0",
      "info": {
        "version": "v1",
        "title":"Sample REST API",
        "x-logo": {
          "url": "https://rebilly.github.io/ReDoc/petstore-logo.png",
          "altText": "Aimia Logo"
        }
      },

    }

非常感谢您在 swagger.json 文件的正确部分提供x-logo 的任何帮助或建议。

【问题讨论】：

标签： swagger asp.net-core-webapi swashbuckle

【解决方案1】：

输入问题后，我自己找到了解决方案。不要直接将扩展添加到 swaggerDoc，而是将其添加到 swaggerDoc.Info 对象。

public class XLogoDocumentFilter : IDocumentFilter
        {
            public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
            {   
              // need to check if extension already exists, otherwise swagger 
              // tries to re-add it and results in error  
              if (!swaggerDoc.Info.Extensions.ContainsKey("x-logo"))
              {
                 swaggerDoc.Info.Extensions.Add("x-logo", new {
                    url = "https://URL/To/The/Logo",
                    altText = "Logo",
                });
              }           

            }

        }

【讨论】：

在最新版本的 SwashBuckle 中不再工作

【解决方案2】：

新版本的 Swashbuckle 在 SwaggerDoc 设置中支持此功能：

c.SwaggerDoc("v1", new OpenApiInfo
{
  Title = ApiDescription,
  Version = "v1",
  Extensions = new Dictionary<string, IOpenApiExtension>
    {
      {"x-logo", new OpenApiObject
        {
           {"url", new OpenApiString("https://blah.com/logo")},
           { "altText", new OpenApiString("The Logo")}
        } 
      }
    }
});

【讨论】：

【解决方案3】：

适用于 .NET core 2.2 及更高版本

public class XLogoDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // need to check if extension already exists, otherwise swagger 
        // tries to re-add it and results in error  
        if (!swaggerDoc.Info.Extensions.ContainsKey("x-logo"))
            swaggerDoc.Info.Extensions.Add("x-logo", new OpenApiObject
            {
                {"url", new OpenApiString("https://www.petstore.com/assets/images/logo.png")},
                {"backgroundColor", new OpenApiString("#FFFFFF")},
                {"altText", new OpenApiString("PetStore Logo")}
            });
    }

}

【讨论】：