3步搞定Swagger UI与ASP.NET Core集成：自动生成API文档的完整指南-优快云博客

3步搞定Swagger UI与ASP.NET Core集成：自动生成API文档的完整指南

【免费下载链接】swagger-ui 项目地址: https://gitcode.com/gh_mirrors/swa/swagger-ui

你是否还在为ASP.NET Core API编写枯燥的文档？是否希望前端团队能实时查看最新接口定义？本文将通过3个简单步骤，教你如何将Swagger UI无缝集成到.NET项目中，实现API文档的自动生成与实时更新。读完本文，你将获得：ASP.NET Core项目中配置Swagger的完整流程、自定义API文档的实用技巧、以及Swagger UI高级功能的应用方法。

准备工作：理解Swagger UI与OpenAPI规范

Swagger UI是一个基于Web的交互式API文档工具，它能够从OpenAPI规范（前身为Swagger规范）自动生成可视化界面。OpenAPI规范是一种用于描述RESTful API的标准格式，支持JSON和YAML两种格式。Swagger UI与OpenAPI规范的兼容性如下表所示：

Swagger UI 版本	发布日期	OpenAPI 规范兼容性	备注

在ASP.NET Core项目中，我们通常通过Swashbuckle.AspNetCore库来生成OpenAPI文档，再结合Swagger UI实现交互式文档功能。Swagger UI支持多种配置方式，包括配置对象、外部配置文件和URL查询参数，优先级从低到高依次为：配置对象 < 外部配置文件 < URL查询参数。

第一步：安装与基础配置

1.1 创建ASP.NET Core项目

首先，创建一个新的ASP.NET Core Web API项目。如果使用Visual Studio，可以通过"创建新项目"向导选择"ASP.NET Core Web API"模板。如果使用命令行，可以运行以下命令：

dotnet new webapi -n SwaggerDemo
cd SwaggerDemo

1.2 安装Swashbuckle.AspNetCore

Swashbuckle.AspNetCore是一个.NET库，它可以为ASP.NET Core应用程序生成OpenAPI文档，并集成Swagger UI。通过NuGet安装：

dotnet add package Swashbuckle.AspNetCore

1.3 配置Swagger中间件

在Program.cs文件中添加Swagger服务和中间件配置：

var builder = WebApplication.CreateBuilder(args);

// 添加Swagger生成器
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo 
    { 
        Title = "My API", 
        Version = "v1",
        Description = "ASP.NET Core Web API with Swagger UI integration"
    });
});

var app = builder.Build();

// 开发环境中启用Swagger和Swagger UI
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        // 可选：设置Swagger UI的路径，默认为"/swagger"
        // c.RoutePrefix = string.Empty; // 将Swagger UI设置为应用的根路径
    });
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

1.4 运行项目并访问Swagger UI

启动应用程序，访问https://localhost:<port>/swagger即可看到Swagger UI界面。如果将RoutePrefix设置为空字符串，则直接访问https://localhost:<port>即可。

Swagger UI的核心配置参数包括：

url: 指定OpenAPI文档的URL，默认为/swagger/v1/swagger.json
dom_id: Swagger UI渲染的DOM元素ID，默认为#swagger-ui
presets: 预设配置，通常使用SwaggerUIBundle.presets.apis和SwaggerUIStandalonePreset

更多配置参数可参考Swagger UI配置文档。

第二步：自定义API文档与Swagger UI

2.1 添加API文档注释

为控制器和操作方法添加XML注释，Swashbuckle会自动将这些注释包含到OpenAPI文档中。首先，在项目属性中启用XML文档文件生成：

右键项目，选择"属性"
在"生成"选项卡中，勾选"XML文档文件"
指定输出路径，如bin\Debug\net6.0\SwaggerDemo.xml

然后，在AddSwaggerGen配置中添加XML文件路径：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo 
    { 
        Title = "My API", 
        Version = "v1",
        Description = "ASP.NET Core Web API with Swagger UI integration"
    });
    
    // 添加XML注释
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

现在，为控制器添加注释：

/// <summary>
/// 管理天气数据的API
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    /// <summary>
    /// 获取天气预测数据
    /// </summary>
    /// <param name="days">预测天数</param>
    /// <returns>天气预测数组</returns>
    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get([FromQuery] int days = 5)
    {
        // 实现代码
    }
}

2.2 自定义Swagger UI显示

Swagger UI提供了多种配置选项来自定义显示效果。例如，设置默认展开深度、启用过滤功能、自定义布局等：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.DocExpansion(DocExpansion.List); // 控制文档展开方式：List(仅展开标签)、Full(全部展开)、None(不展开)
    c.EnableFilter(); // 启用过滤功能
    c.DisplayOperationId(); // 显示操作ID
    c.DefaultModelExpandDepth(2); // 设置模型默认展开深度
    c.DefaultModelsExpandDepth(-1); // 隐藏模型部分，设为-1完全隐藏
    c.ShowExtensions(); // 显示扩展属性
});

常用的显示配置参数包括：

参数名	类型	默认值	描述
`docExpansion`	String	"list"	控制文档展开方式，可选值："list"、"full"、"none"
`filter`	Boolean	false	是否启用过滤功能
`displayOperationId`	Boolean	false	是否显示操作ID
`defaultModelsExpandDepth`	Number	1	模型默认展开深度，设为-1隐藏模型

2.3 添加安全定义

对于需要认证的API，可以通过Swagger UI配置安全定义，如JWT认证：

builder.Services.AddSwaggerGen(c =>
{
    // ... 其他配置 ...
    
    // 添加JWT认证
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "JWT授权(数据将在请求头中进行传输) 在下方输入Bearer {token}",
        Name = "Authorization", // JWT默认参数名称
        In = ParameterLocation.Header, // JWT存储在请求头
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });
    
    c.AddSecurityRequirement(new OpenApiSecurityRequirement {
        {
            new OpenApiSecurityScheme {
                Reference = new OpenApiReference {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] {}
        }
    });
});

配置完成后，Swagger UI会显示一个"Authorize"按钮，用户可以输入JWT令牌进行认证。

第三步：高级功能与部署

3.1 使用Swagger UI插件

Swagger UI支持插件扩展，可以通过配置plugins参数添加自定义插件。例如，添加请求代码片段插件：

SwaggerUIBundle({
  // ... 其他配置 ...
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl,
    SwaggerUIBundle.plugins.RequestSnippets
  ],
  requestSnippetsEnabled: true,
  requestSnippets: {
    generators: {
      curl_bash: {
        title: "cURL (bash)",
        syntax: "bash"
      },
      csharp: {
        title: "C#",
        syntax: "csharp"
      }
    }
  }
})

3.2 部署Swagger UI

在生产环境中部署Swagger UI时，需要考虑安全性和性能。以下是几种常见的部署方式：

3.2.1 使用Docker容器

Swagger UI提供了官方Docker镜像，可以直接部署：

docker pull swaggerapi/swagger-ui
docker run -p 80:8080 -e URL=/swagger/v1/swagger.json swaggerapi/swagger-ui

如果需要自定义配置，可以通过环境变量传递：

docker run -p 80:8080 \
  -e URL=/swagger/v1/swagger.json \
  -e DEEP_LINKING=true \
  -e DISPLAY_OPERATION_ID=true \
  swaggerapi/swagger-ui

3.2.2 静态文件部署

可以将Swagger UI构建为静态文件，然后部署到CDN或静态文件服务器。首先，安装Swagger UI npm包：

npm install swagger-ui-dist

然后，创建一个HTML文件，引入Swagger UI资源：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Swagger UI</title>
  <link rel="stylesheet" href="node_modules/swagger-ui-dist/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = () => {
      window.ui = SwaggerUIBundle({
        url: "/swagger/v1/swagger.json",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        layout: "StandaloneLayout"
      });
    };
  </script>
</body>
</html>

3.2.3 在ASP.NET Core中限制Swagger UI访问

在生产环境中，可以通过环境变量或配置文件控制Swagger UI的启用：

if (app.Environment.IsDevelopment() || app.Configuration.GetValue<bool>("EnableSwagger"))
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

然后在appsettings.json中添加配置：

{
  "EnableSwagger": false
}

在需要访问Swagger UI的环境中，通过环境变量覆盖配置：

ASPNETCORE_EnableSwagger=true dotnet run

总结与展望

通过本文介绍的三个步骤，你已经掌握了如何在ASP.NET Core项目中集成Swagger UI，实现API文档的自动生成与自定义显示。Swagger UI不仅提高了API开发效率，还大大改善了前后端协作流程。未来，你可以进一步探索Swagger UI的高级功能，如：

自定义插件开发
多版本API文档管理
与测试工具集成

希望本文对你有所帮助，如果你有任何问题或建议，欢迎在评论区留言。别忘了点赞、收藏本文，关注作者获取更多.NET开发技巧！

参考资料

【免费下载链接】swagger-ui 项目地址: https://gitcode.com/gh_mirrors/swa/swagger-ui

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考