如何使用 NSwag 的 UseSwaggerUi3 加载自定义样式表答案

【问题标题】：How to load custom stylesheet with NSwag's UseSwaggerUi3如何使用 NSwag 的 UseSwaggerUi3 加载自定义样式表
【发布时间】：2019-05-05 21:42:37
【问题描述】：

我正在尝试使用自己的 .css 样式表自定义 swagger UI。

我正在使用 asp net core 2.1 和 NSwag.AspNetCore 12.2.5。

我四处搜索，发现在以前的版本中，这是通过嵌入我的自定义样式表，然后将其注入到我的中间件配置中来完成的：

app.UseSwagger(o =>
{
   o.InjectStylesheet("/css/custom.css");
});

在最新版本的 NSwag 中，这似乎已更改为：

app.UseSwaggerUi3(cfg =>
{
   cfg.CustomStylesheetUri = new Uri("/css/custom.css", UriKind.Relative);
});

但是要么我没有使样式表可用，要么我的 uri 没有正确指向它。

我不完全理解 Web 服务器如何提供 swagger 文件（我假设它们是从 NSwag nuget 包中加载的，但我没有在我的构建输出文件夹中看到它们），所以我假设我不是使样式表正确可用。

执行上述操作，我看到<link rel="stylesheet" href="css/custom.css">添加到swagger index.html，但chrome开发人员工具说找不到该文件。

我尝试过： 1. 将我的样式表添加到 wwwroot。 2. 在项目的某处添加我的样式表，并将其显式复制到我的 csproj 的输出文件夹中。 3. 将我的样式表嵌入到构建工件中。

我的中间件管道中有.UseStaticFiles()。

我错过了什么？有没有人有一个可行的例子？

【问题讨论】：

标签： c# asp.net-core swagger nswag

【解决方案1】：

主要答案

如果不存在，请在您的项目中创建一个wwwroot 文件夹，并在wwwroot 文件夹中创建子文件夹，例如css、img、js，这样您就可以拥有如下内容：

wwwroot\css
wwwroot\img
wwwroot\js

UseStaticFiles() 方法查找 wwwroot 文件夹并使其可服务。

接下来您需要确保项目的 .csproj 文件包含以下内容：

  <ItemGroup>
    <None Include="wwwroot\*" />
  </ItemGroup>

这基本上说 wwwroot 下的所有子文件夹和文件都将被发布。

设置好这些东西后，您的 cfg.CustomStylesheetUri = new Uri("/css/custom.css", UriKind.Relative) 代码现在应该可以工作了。

备用选项

作为另一种选择，如果您想从 wwwroot 之外的不同目录提供您的 css 文件，那么您需要在 UseStaticFiles() 方法中指定 StaticFileOptions 参数以提供您的 css。这是我的工作示例，但带有ReDoc。

我正在使用NSwag，它扩展了 Swagger 来生成和进一步自定义我的 OpenAPI 规范文件。（通过 NSwag 的 ReDoc 使用 CustomStylesheetUri insead 或 InjectStylesheet，但我想它的工作方式相同。

        app.UseStaticFiles(new StaticFileOptions
        {
            FileProvider = new PhysicalFileProvider(
                Path.Combine(Directory.GetCurrentDirectory(), "Content")),
            RequestPath = "/Content"
        });

        app.UseSwagger();
        app.UseSwaggerUi3();
        app.UseReDoc(c => {
            c.Path = "/redoc";
            c.DocumentPath = "/swagger/v1/swagger.json";
            c.CustomStylesheetUri = new Uri("/Content/redoc-styles.css", UriKind.Relative); //added towards the end of the <head>
            c.CustomJavaScriptUri = new Uri("/Content/redoc-javascript.js", UriKind.Relative);  //added at the end of the <body>
        });

上面的代码引用了我创建的名为 Content 的文件夹，我在其中添加了 css 和 js 文件。我的文件夹位于项目的根目录：MyAPIProject/Content/redoc-styles.css

除了这个次要示例之外，还要确保您的 .csproj 文件包含相关条目（否则不会发布文件夹和文件）：

  <ItemGroup>
    <Content Include="Content\css\redoc-styles.css">
      <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    </Content>
    <Content Include="Content\js\redoc-javascript.js">
      <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
    </Content>
  </ItemGroup>

【讨论】：

谢谢。我认为我的错误是认为dotnet build/dotnet run 默认会复制 wwwroot ，就像dotnet publish 一样，但事实并非如此。因此，在 IDE 中调试时，我的样式表不是我的应用程序所期望的。为了简单起见，我最终将样式表放在 wwwroot/swagger 中，因为这是 swagger 用于其文件的文件夹名称，然后仅使用 new Uri("custom.css", UriKind.Relative)。

【解决方案2】：

我建议您使用Swashbuckle。所以你的代码会是这样的

我的例子。请确保您的中间件顺序正确

app.UseStaticFiles();

// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();

// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint($"/swagger/v1/swagger.json", "Awesome CMS Core API V1");
    c.InjectStylesheet("/swagger-ui/custom.css"); //css in your wwwrootfolder 
});


// Register the Swagger generator, defining one or more Swagger documents
services.AddSwaggerGen(c =>
{
  c.SwaggerDoc("v1", new Info
  {
    Version = "v1",
    Title = "Awesome CMS Core API V1",
    Contact = new Contact { Name = "Tony Hudson", Email = "", Url = "https://github.com/ngohungphuc" }
  });
});

【讨论】：

感谢您的建议。如果我不知道如何使用 NSwag 来做这件事，我会回过头来，但 NSwag 似乎确实支持这一点，所以我会首先尝试了解我缺少什么。
github.com/RicoSuter/NSwag/blob/master/src/… github.com/RicoSuter/NSwag/blob/master/src/… 看看这些
这是一个关于这个github.com/RicoSuter/NSwag/issues/1137的问题