在 .NET 9 中让您的 OpenAPI（Swagger）文档 UI 变得出色

        从 .NET 9 开始，默认模板中不再包含 Swagger UI webapi。虽然文档仍然包含在内，但现在通过调用MapOpenApi，UI 不再存在。很高兴，重新获得文档 UI 相对容易。但 UI 本来就很无聊，所以让我们来点更花哨的东西吧！

认识 Scalar
        假设我们已经通过dotnet new webapi命令创建了新的 .NET 9 API 项目。现在，为了获得新外观，我们将使用一个名为 Scalar 的库。我们需要为此安装它们的 nuget 包：

dotnet add package Scalar.AspNetCore

        由于我们已经在模板中有了AddOpenApi并MapOpenApi调用，剩下要做的就是映射 UI 页面，Scalar 调用ApiReference如下：

app.MapScalarApiReference();

        所以现在如果运行我们的 api 并打开路径，/scalar/v1我们应该会看到我们的新 UI！Scalar 带有 10 个内置主题，让我们研究一下它们

主题 2：默认
默认情况下，我们将获得主题＃2，又称默认主题，如下所示：

        在我看来，该主题看起来比 Swagger UI 更酷、更现代，但当然，继续使用默认主题是很无聊的，让我们研究一下还有什么

        您可能还会注意到，除了默认的天气预报之外，还有几个端点，如果您想使用它们，这里是其余端点的代码：

app.MapPost("/weatherforecast", (WeatherForecast forecast) =>
{
    return forecast;
});

app.MapPut("/pets/{id}", (string id) =>
{
    return id;
});
app.MapDelete("/pets/{id}", (string id) =>
{
    return id;
});

主题 0：无
有趣的是，除了默认主题之外，我们还有一个None主题。为了进行实验，我们可以在不同的路线上提供几个主题。以下是我们如何将主题添加None到none/v1路线：

app.MapScalarApiReference(o => 
    o.WithTheme(ScalarTheme.None)
    .WithEndpointPrefix("none/{documentName}")
);

我们将看到以下内容：

        乍一看，它可能与默认主题完全相同。然而，面对面对比后，我似乎注意到主题None略浅一些。但我想，差异太小了，所以让我们继续搜索。

主题 1：另类

嗯，主题只是少了一些颜色。这绝对不是我所说的花哨。

主题三：月亮

        说实话，这是我最不喜欢的主题。虽然颜色不是标准的，但我也不会称其为花哨。对我来说，这些颜色给人一种不健康的感觉。我们去下一个吧！

主题四：紫色 

这一个比月亮更令人愉快，但仍然很无聊！下一个！

主题 5：日光化

        嗯……和月亮主题一样令人讨厌。该主题似乎只是通过添加一些令人不快的颜色使文本更难读。我们最终会得到更好的东西吗？

主题六：蓝色星球

        最后，来点有创意的东西。我很容易想象有人会选择这个主题。不过这不符合我的口味，我想我只是不太喜欢蓝色主题。

主题 7：土星

        你可能会问，这与默认主题有什么不同？好吧，将它们并排摆在一起，我可以向你保证，这是最黑的主题，所以如果你想要最大的对比度，这就是你的选择！

主题 8：开普勒

        嗯，又是一个蓝色主题，但颜色要深得多，我个人更喜欢这个。但仍然不够有趣。

主题 9：火星

        这是最鼓舞人心的主题。我想这将是 SpaceX 文档页面的完美主题。但是，对于常规 API，我担心它会很快饱和。我想为我的文档找到更通用的东西。

主题 10：深空

        这个主题也很有启发性，符合我的标准，既要花哨又要专业。尽管背景是一张图片，但它也给人一种简约的感觉。

额外的自定义
        Scalar 文档说他们也有经典布局，但我在他们的配置 API 中找不到该选项。（我尝试了他们所有的选项）。你可以做的是使用如下代码删除侧边栏和模型部分：

app.MapScalarApiReference(o => o
    .WithTheme(ScalarTheme.Mars)
    .WithModels(false)
    .WithSidebar(false)
    .WithEndpointPrefix("special/{documentName}")
);

        然而，它实际上只是删除了部分和侧边栏，而没有改变 UI 的任何其他部分，所以我没有发现删除有什么好处。所以我想这就是 Scalar 目前的全部内容。我们将看看他们未来是否会带来更多主题或更有意义的定制！

总结！
        使用 .NET 9 获得美观的 .NET OpenAPI UI 非常容易 — 只需添加Scalar并选择一个主题即可。我选择的主题将是Deep Space主题。主题看起来很有趣，但又不会太过奢华，这使其适合您经常使用的东西。

以下是我将添加到所有新 .NET 项目中的代码行：

app.MapScalarApiReference(o => o.WithTheme(ScalarTheme.DeepSpace));

希望本文能成为您自定义主题的参考。在评论中留下您最喜欢的主题，欢迎收藏、点赞 感谢！

如果您喜欢此文章，请收藏、点赞、评论，谢谢，祝您快乐每一天。