Swashbuckle.AspNetCore 中 SwaggerUI 的配置与自定义指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00954/article/details/148505722

Swashbuckle.AspNetCore 中 SwaggerUI 的配置与自定义指南

Swashbuckle.AspNetCore Swashbuckle.AspNetCore：这是一个用于ASP.NET Core的Swagger文档生成器，适合为RESTful API生成API文档。特点包括自动生成API文档、支持多种输出格式（如Markdown、HTML等）、与ASP.NET Core集成良好等。项目地址: https://gitcode.com/gh_mirrors/sw/Swashbuckle.AspNetCore

前言

Swashbuckle.AspNetCore 是一个流行的 ASP.NET Core 工具，它能自动为你的 Web API 生成 Swagger/OpenAPI 文档。其中，SwaggerUI 组件提供了一个美观且交互式的界面，让开发者可以轻松浏览和测试 API。本文将深入探讨如何配置和自定义 SwaggerUI，以满足各种开发需求。

基础配置

修改 UI 访问路径

默认情况下，SwaggerUI 可以通过 /swagger 路径访问。如果需要修改这个路径，可以在中间件配置中进行调整：

app.UseSwaggerUI(options =>
{
    options.RoutePrefix = "api-docs";
});

这样配置后，SwaggerUI 将通过 /api-docs 路径访问。

自定义文档标题

当同时打开多个 Swagger 页面时，自定义标题有助于区分不同文档：

app.UseSwaggerUI(options =>
{
    options.DocumentTitle = "订单管理 API 文档";
});

资源文件自定义

使用 CDN 资源

默认情况下，SwaggerUI 使用内置的 CSS 和 JavaScript 文件。如果需要使用 CDN 资源，可以这样配置：

app.UseSwaggerUI(options =>
{
    options.StylesPath = "https://cdn.example.com/swagger-ui.min.css";
    options.ScriptBundlePath = "https://cdn.example.com/swagger-ui-bundle.min.js";
    options.ScriptPresetsPath = "https://cdn.example.com/swagger-ui-standalone-preset.min.js";
});

多文档支持

如果你的 API 有多个版本，可以同时展示多个文档：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "API 版本 1");
    options.SwaggerEndpoint("/swagger/v2/swagger.json", "API 版本 2");
});

用户可以在界面右上角切换不同版本的文档。

高级 UI 配置

SwaggerUI 提供了丰富的配置选项，可以通过以下方式进行调整：

app.UseSwaggerUI(options =>
{
    // 控制模型展示深度
    options.DefaultModelExpandDepth(2);
    
    // 设置默认模型渲染方式
    options.DefaultModelRendering(ModelRendering.Model);
    
    // 显示操作ID
    options.DisplayOperationId();
    
    // 显示请求耗时
    options.DisplayRequestDuration();
    
    // 文档展开方式
    options.DocExpansion(DocExpansion.None);
    
    // 启用深度链接
    options.EnableDeepLinking();
    
    // 启用过滤器
    options.EnableFilter();
    
    // 限制显示的标签数量
    options.MaxDisplayedTags(5);
});

自定义样式和行为

注入自定义 JavaScript

可以通过添加自定义 JavaScript 文件来扩展 UI 功能：

app.UseSwaggerUI(options =>
{
    options.InjectJavascript("/swagger-ui/custom.js");
});

注入自定义 CSS

要修改 UI 的外观，可以注入自定义样式表：

app.UseSwaggerUI(options =>
{
    options.InjectStylesheet("/swagger-ui/custom.css");
});

完全自定义 UI

如果需要更深入的定制，可以提供自定义的 index.html 文件：

app.UseSwaggerUI(options =>
{
    options.IndexStream = () => Assembly.GetExecutingAssembly()
        .GetManifestResourceStream("YourProject.Swagger.index.html");
});

OAuth2.0 集成

SwaggerUI 支持 OAuth2.0 授权流程，可以这样配置：

app.UseSwaggerUI(options =>
{
    options.OAuthClientId("your-client-id");
    options.OAuthClientSecret("your-client-secret");
    options.OAuthScopes("api.read", "api.write");
    options.OAuthUsePkce();
});

请求和响应拦截器

可以通过拦截器修改请求或处理响应：

app.UseSwaggerUI(options =>
{
    options.UseRequestInterceptor("(req) => { req.headers['X-Custom-Header'] = 'Value'; return req; }");
    options.UseResponseInterceptor("(res) => { console.log('Received response:', res); return res; }");
});