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

Question

我正在尝试使用我自己的 .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()。

我错过了什么？有人有工作示例吗？

Answer 1

我建议您使用 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" }
  });
});

Answer 2

主要答案

如果不存在，请在项目中创建一个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 规范文件。（ReDoc via NSwag 使用 CustomStylesheetUri 而不是 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>

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

How to load custom stylesheet with NSwag's UseSwaggerUi3

c#

swagger

asp.net-core

nswag

主要答案

备用选项