在.NET Core的Swagger/Swashbuckle中使用自定义Index.Html的问题 [英] Issue Using Custom Index.Html in Swagger / Swashbuckle for .NET Core

问题描述

我在使用自定义index.html和其他资产时遇到了麻烦. Swashbuckle/Swagger似乎根本无法识别或使用它们.我确实设置了app.UseDefaultFiles()和app.UseStaticFiles().我想了解我做错了什么.

I am having difficulty using a custom index.html and other assets with swashbuckle. Swashbuckle/Swagger do not seem to recognizing or using them at all. I do have app.UseDefaultFiles() and app.UseStaticFiles() set. I am trying to understand what I am doing incorrectly.

我尝试设置与Microsoft文章中定义的配置有些类似的配置，但没有成功. ( https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio )

I have attempted to set up my configuration somewhat similar to what is defined on the Microsoft article without success. (https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio)

我目前正在使用本文中引用的dist文件夹中的文件(

I am presently using the files from the dist folder referenced in the article (https://github.com/swagger-api/swagger-ui/tree/2.x/dist) along with the custom css file provided.

我的index.html文件位于/wwwroot/swagger/ui下 自定义css文件位于/wwwroot/swagger/ui/css(作为custom.css)下

My index.html file is located under /wwwroot/swagger/ui The custom css file is located under /wwwroot/swagger/ui/css (as custom.css)

这是我的Startup.cs类.

Here is my 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();
    }
}

我的最终目标是能够使用类似此处的slate样式主题( https ://github.com/omnifone/slate-swagger-ui ).现在，我只是想让Swashbuckle/Swagger使用Microsoft文档中引用的自定义文件，然后再尝试使其他文件正常工作.

My ultimate objective is to be able to use something like the slate style theme available here (https://github.com/omnifone/slate-swagger-ui). For right now, I am just trying to get Swashbuckle/Swagger to use the customized files referenced in the Microsoft documentation before trying to make the other files work.

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

I really do NOT want to try and convert my assets to embedded resources--since there will many of them. I just want to reference a normal index.html file and be able to use all of its referenced files.

我在做什么错了?

相关软件版本

• .Net Core版本:2.0.3
• Swashbuckle.AspNetCore:1.2.0
• Windows 10 Enterprise Build 1703
• Visual Studio 2017企业版15.5.2

推荐答案

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

Here is the minimum action I found to be necessary to replace SwashBuckle's index.html in a .NET Core project:

• 从此处获取原始index.html的副本:将该副本放置在项目的某些子文件夹中.
  该文件的名称可能不同，我选择了: \Resources\Swagger_Custom_index.html

  Place that copy in some sub-folder of your project.
  The file may have a different name, I chose: \Resources\Swagger_Custom_index.html

  在解决方案资源管理器中右键单击该文件，选择属性"，然后在左窗格中选择配置属性".在右窗格的高级"下，找到构建操作"条目并将其设置为嵌入式资源".单击确定.

  Right-click that file in Solution Explorer, select 'Properties', select 'Configuration Properties' in left pane. Under 'Advanced' in right pane find entry 'Build Action' and set it to 'Embedded resource'. Click Ok.

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

  In Startup.cs add the following line to your app.UseSwaggerUI() call:

  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方法中文件资源的标识符由以下组成:

• The identifier for the file resource in the above GetManifestResourceStream method is composed of:

  1. 您的默认名称空间(即"Your.Default.Namespace")
  2. 资源(即资源")的子路径
  3. 资源的文件名(即'Swagger_Custom_index.html')

  所有三个部分都用点连接(此处没有反斜杠或反斜杠).
  如果您不使用子路径，但是将您的资源放在根目录中，则只需省略第2部分.

  All three parts are concatenated using dots (NO slashes or backslashes here).
  If you don't use a sub-path but have your resource in root, just omit part 2.

  这篇关于在.NET Core的Swagger/Swashbuckle中使用自定义Index.Html的问题的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！