在 .NET Core 的 Swagger / Swashbuckle 中使用自定义 Index.Html 问题

Question

我在使用自定义 index.html 和其他带有 swashbuckle 的资产时遇到困难。 Swashbuckle/Swagger 似乎根本无法识别或使用它们。我确实设置了 app.UseDefaultFiles() 和 app.UseStaticFiles() 。我试图了解我做错了什么。

我试图设置我的配置，但未成功，这与 Microsoft 文章中定义的配置有些相似。 (https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio)

我目前正在使用文章 (https://github.com/swagger-api/swagger-ui/tree/2.x/dist) 中引用的 dist 文件夹中的文件以及提供的自定义 css 文件。

我的 index.html 文件位于 /wwwroot/swagger/ui 下自定义 css 文件位于 /wwwroot/swagger/ui/css 下（如 custom.css）

这是我的 Startup.cs class.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
             .AddJsonOptions(options =>
             {
                 // Swagger - Format JSON
                 options.SerializerSettings.Formatting = Formatting.Indented;
             });

        // Register the Swagger generator, defining one or more Swagger documents
        services.AddSwaggerGen(c =>
        {
            c.DescribeAllEnumsAsStrings();
            c.DescribeStringEnumsInCamelCase();
            // c.DescribeAllParametersInCamelCase();                

            c.SwaggerDoc("v1",
                new Info
                {
                    Title = "My Web API - v1",
                    Version = "v1",
                    Description = "New and improved version. A simple example ASP.NET Core Web API. "

                }
            );

            c.SwaggerDoc("v2",
                new Info
                {
                    Title = "My Web API - v2",
                    Version = "v2",
                    Description = "New and improved version. A simple example ASP.NET Core Web API. "
                }
            );

            // Set the comments path for the Swagger JSON and UI.
            var basePath = AppContext.BaseDirectory;
            var xmlPath = Path.Combine(basePath, "ApiTest.xml");
            c.IncludeXmlComments(xmlPath);
        });

    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        string swaggerUIFilesPath = env.WebRootPath + "\swagger\ui";

        if (!string.IsNullOrEmpty(swaggerUIFilesPath))
        {
            app.UseDefaultFiles();
            app.UseStaticFiles(new StaticFileOptions
            {
                FileProvider = new PhysicalFileProvider(swaggerUIFilesPath),
                RequestPath = new PathString("/api-docs"),
            });
        }

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger(c =>
        {
            c.RouteTemplate = "api-docs/{documentName}/swagger.json";
        });

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            //c.ShowJsonEditor();
            c.RoutePrefix = "api-docs";
            c.SwaggerEndpoint("/api-docs/v1/swagger.json", "My Web API - V1 ");
            c.SwaggerEndpoint("/api-docs/v2/swagger.json", "My Web API - V2 ");
            c.DocumentTitle("My Web API");
        });

        app.UseMvc();
    }
}

我的最终目标 objective 是能够使用类似这里可用的石板风格主题的东西 (https://github.com/omnifone/slate-swagger-ui)。目前，我只是想让 Swashbuckle/Swagger 在尝试使其他文件工作之前使用 Microsoft 文档中引用的自定义文件。

我真的不想尝试将我的资产转换为嵌入式资源——因为会有很多。我只想引用一个普通的 index.html 文件并能够使用它的所有引用文件。

我做错了什么？

相关软件版本

.Net核心版本：2.0.3
Swashbuckle.AspNetCore: 1.2.0
Windows 10 企业内部版本 1703
Visual Studio 2017 企业版 15.5.2

Answer 1

这是我发现在 .NET Core 项目中替换 SwashBuckle 的 index.html 所需的最少操作：

从此处获取原始 index.html 的副本：https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/src/Swashbuckle.AspNetCore.SwaggerUI/index.html
将该副本放在项目的某个子文件夹中。
该文件可能有不同的名称，我选择了： \Resources\Swagger_Custom_index.html
在解决方案资源管理器中右键单击该文件，在左窗格中 select 'Properties'、select 'Configuration Properties'。在右窗格的 'Advanced' 下找到条目 'Build Action' 并将其设置为 'Embedded resource'。单击确定。

在 Startup.cs 中将以下行添加到您的 app.UseSwaggerUI() 调用中：

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    //...

    app.UseSwaggerUI(c =>
    {
        c.IndexStream = () => GetType().GetTypeInfo().Assembly.GetManifestResourceStream("Your.Default.Namespace.Resources.Swagger_Custom_index.html");
    });

    //...
}

上述GetManifestResourceStream方法中文件资源的标识符组成：
1. 您的默认命名空间（即 'Your.Default.Namespace'）
2. 您的资源的子路径（即 'Resources'）
3. 资源的文件名（即 'Swagger_Custom_index.html'）
所有三个部分都使用点连接（此处没有斜线或反斜线）。
如果您不使用子路径但将您的资源放在根目录中，则省略第 2 部分。

Answer 2

对于在 ASP.NET Core 上分离 ApplicationBuilder 配置方法的人：

如果分隔的 method/class 是静态的，则无法调用 GetType()，因为需要对象引用。

在这种情况下，将 GetType() 切换为 MethodBase.GetCurrentMethod().DeclaringType

c.IndexStream = () => MethodBase.GetCurrentMethod().DeclaringType.Assembly.GetManifestResourceStream("xxx.index.html");

在 .NET Core 的 Swagger / Swashbuckle 中使用自定义 Index.Html 问题

Issue Using Custom Index.Html in Swagger / Swashbuckle for .NET Core

swagger

swagger-2.0

swashbuckle

asp.net-core-2.0