IRONSOFTWAREHOME
IRONSUITE所有10的价格为2
联系销售
按公司
加入我们的专家网络
开发者更新

Swashbuckle ASP .NET Core（开发者如何使用）

Jacob Mellor，Team Iron 的首席技术官
Jacob Mellor
Updated: 2026年4月21日

Swashbuckle 是一个 C# .NET Core NuGet 包，帮助自动记录 RESTful Web API。在这篇博客中，我们将探索 Swashbuckle ASP.NET Core 和 IronPDF 安装说明 NuGet 包，支持现代 ASP.NET Core Web API 的开发。它们共同提供了一系列功能，能够通过最少的代码实现。

API文档页面是使用Swagger UI工具显示的，该工具使用了从Web API项目生成的swagger.json文件。 生成的 JSON 文档遵循 Open API 标准。 Swashbuckle 作为 NuGet 包 Swashbuckle.AspNetCore 提供，安装和配置后将自动公开 Swagger JSON。 Swagger UI 工具读取从 API 上编写的 XML 注释生成的 Swagger JSON 文件。此外，启用项目设置文件后还可以创建 XML 文档文件。将 XML 注释转换为 XML 文档文件，然后生成 Swagger JSON。 然后，Swagger 中间件读取 JSON 并公开 Swagger JSON 端点。

.NET Core Web API 项目内的实现

让我们从一个 Web API 项目开始：

dotnet new webapi -n SwashbuckleDemo
cd SwashbuckleDemo
dotnet build
dotnet add package Swashbuckle.AspNetCore --version 6.5.0
dotnet build
SHELL

在这里，我们创建一个名为"SwashbuckleDemo"的 web API 项目，然后使用包管理器控制台将 Swashbuckle 包安装到 .NET Core Web API 项目。

配置 Swagger 中间件

在Startup.cs文件中配置Swagger服务。

using System.Reflection;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Other service configurations...

        // Register the Swagger generator
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

            // Optionally, include XML comments for additional information
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        // Other app configurations...

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

        // Enable Swagger UI (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }
}

添加 todo 列表 API 的控制器：

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Builder;
using Microsoft.EntityFrameworkCore;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

// Example to define an entity class
public class Todo
{
    public int Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

// Example to define a DbContext class
public class TodoDb : DbContext
{
    public DbSet<Todo> Todos => Set<Todo>();
}

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "SwashbuckleDemo!");

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id) is Todo todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();
    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);
    if (todo is null) return Results.NotFound();
    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;
    await db.SaveChangesAsync();
    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.Ok(todo);
    }

    return Results.NotFound();
});

app.Run();

可以按如下方式添加控制器：

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System;
using System.Linq;

namespace RestFullMinimalApi.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }
    }
}

上面的代码可以在 GitHub - Swashbuckle Demo 上找到。

Swashbuckle 提供以下功能

Swagger UI 工具

Swashbuckle ASP .NET Core (开发者如何使用): 图1 - Swagger UI工具

Swagger UI 可从 Web API 应用程序的基本 URL 通过"/swagger/index.html"访问。 它列出了代码中的所有 REST API。 Swagger 生成器读取 JSON 文件并填充 UI。

Swagger JSON

Swashbuckle.AspNetCore 会自动生成 Swagger JSON 文件，其中包含有关 API 结构的信息，包括端点、请求和响应类型等详细信息。 其他支持 Swagger/OpenAPI 标准的工具和服务可以使用此 JSON 文件。

Swagger JSON 文件可从 web API 应用程序的基本 URL 通过"/swagger/v1/swagger.json"访。

Swashbuckle ASP .NET Core (开发者如何使用): 图2 - swagger JSON文件。

代码注释

开发人员可以在其 ASP.NET Core 控制器中使用 XML 注释和属性，为 Swagger 文档提供附加信息。 这包括描述、示例和其他元数据，以增强生成的 Swagger 文档。

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    /// <summary>
    /// Retrieves WeatherForecast
    /// </summary>
    /// <remarks>Awesomeness!</remarks>
    /// <response code="200">Retrieved</response>
    /// <response code="404">Not found</response>
    /// <response code="500">Oops! Can't lookup your request right now</response>
    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

配置选项

Swashbuckle.AspNetCore 提供各种配置选项以自定义 Swagger 文档的生成方式。 开发人员可以控制哪些 API 被记录、配置命名约定以及调整其他设置。

以下是 Swashbuckle.AspNetCore 提供的一些关键配置选项：

SwaggerGen 选项

c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

此行指定了 Swagger 文档版本，并包括元数据，例如 API 的标题和版本。

c.IncludeXmlComments(xmlPath);

此选项允许您包含代码中的 XML 注释，以在 Swagger 文档中提供附加信息。 xmlPath变量应指向您的XML注释文件所在的位置。

c.DescribeAllParametersInCamelCase();

此选项将 Swagger 生成器配置为使用 camelCase 作为参数名称。

c.OperationFilter<CustomOperationFilter>();

您可以注册自定义操作过滤器，以修改特定操作的 Swagger 文档。 IOperationFilter的类。

Swagger UI 选项

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

此行配置 Swagger UI 以显示文档。 第一个参数是 Swagger JSON 文件的 URL，第二个参数是 API 版本的用户友好名称。

c.RoutePrefix = "swagger";

您可以设置 Swagger UI 的路由前缀。 在此示例中，Swagger UI 将在 /swagger 可用。

c.DocExpansion(DocExpansion.None);

此选项控制 Swagger UI 显示 API 文档的方式。 DocExpansion.None默认会收起所有操作。

SwaggerOptions

c.SerializeAsV2 = true;

此选项指定是否以2.0格式(false)序列化Swagger文档。 如果您想使用Swagger 2.0，请将其设置为true。

c.DisplayOperationId();

此选项在 Swagger UI 中显示操作 ID，对于调试和理解您的 API 结构很有用。

c.OAuthClientId("swagger-ui");

如果您的 API 使用 OAuth 认证，您可以为 Swagger UI 配置 OAuth 客户端 ID。

这些只是可用配置选项的一些例子。 Swashbuckle.AspNetCore 库高度可定制，您可以通过组合各种选项和过滤器来定制 Swagger 文档，以满足您的特定需求。 始终参考官方文档或开发环境中的 IntelliSense，以获取最最新和最全面的可用选项信息。

IronPDF 简介

IronPDF 产品概述 是来自 Iron Software 网站 的 C# PDF 库，帮助读取和生成 PDF 文档。 它可以轻松地将带有样式信息的格式化文档转换为 PDF。 IronPDF 可以轻松地从 HTML 内容生成 PDF。 它可以从 URL 下载 HTML 内容，然后生成 PDF。

IronPDF 是将网页、URL 和 HTML 转换为 PDF 的优秀工具，可以完美复制源内容。 非常适合生成在线内容（如报告和发票）的 PDF，并且可以轻松创建任何网页的 PDF 版本。

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

安装

通过 NuGet 安装 IronPDF 使用 NuGet 包管理器详细信息 或 Visual Studio 安装指南 包管理器控制台。

在包管理器控制台中输入命令：

PM > Install-Package IronPdf

使用 Visual Studio

Swashbuckle ASP .NET Core（开发人员视角）：图 3 - 在 Visual Studio 中打开项目。 转到"工具"菜单，选择"NuGet 包管理器"，然后选择"为解决方案管理 NuGet 包"。 在NuGet包管理器界面中，在浏览选项卡中搜索包"IronPDF"。 然后选择并安装 IronPDF 的最新版本。

现在，让我们修改应用程序，以添加功能将网站内容下载为 PDF 文件。

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using IronPdf;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

namespace RestFullMinimalApi.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }

        /// <summary>
        /// Retrieves WeatherForecast as Pdf
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet("download", Name = "DownloadWeatherForecast")]
        public IActionResult GetWeatherPdf()
        {
            var results = Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            }).ToArray();

            var html = GetHtml(results);
            var renderer = new ChromePdfRenderer();
            var pdf = renderer.RenderHtmlAsPdf(html);
            var fileName = "WeatherReport.pdf";
            pdf.SaveAs(fileName);

            var stream = new FileStream(fileName, FileMode.Open);
            // Return the PDF file for download
            return new FileStreamResult(stream, "application/octet-stream") { FileDownloadName = fileName };
        }

        private static string GetHtml(WeatherForecast[] weatherForecasts)
        {
            string header = @"
<html>
<head><title>WeatherForecast</title></head>
<body>
<h1>WeatherForecast</h1>
";

            var footer = @"
</body>
</html>";

            var htmlContent = header;
            foreach (var weather in weatherForecasts)
            {
                htmlContent += $@"
    <h2>{weather.Date}</h2>
    <p>Summary: {weather.Summary}</p>
    <p>Temperature in Celsius: {weather.TemperatureC}</p>
    <p>Temperature in Fahrenheit: {weather.TemperatureF}</p>
";
            }
            htmlContent += footer;
            return htmlContent;
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }
        
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

在这里，我们使用天气数据生成一个 HTML 字符串，然后将其用于创建 PDF 文档。

HTML 内容

Swashbuckle ASP .NET Core (开发者如何使用): 图4 - 天气预报的HTML内容。

PDF 报告如下所示：

Swashbuckle ASP .NET Core (开发者如何使用): 图5 - HTML到PDF的输出文件：WeatherReport.pdf

整段代码可在 GitHub - Swashbuckle Demo 源代码中找到。
文档上有一个试用许可证的小水印，可以通过有效许可证移除。

许可（提供免费试用）

为了让上述代码工作，需要许可证密钥。 将此密钥放置在appsettings.json文件中。

{
    "IronPdf": {
        "LicenseKey": "your license key"
    }
}
JSON

注册 IronPDF 试用注册 后，开发人员可获得试用许可证。 试用许可证无需信用卡。 使用您的电子邮件地址注册以获得免费试用。

结论

理解 Swashbuckle 和 IronPDF，可以有效地在您的 ASP.NET Core 应用程序中集成 API 文档和 PDF 生成能力。 IronPDF 还提供有关 入门指南 和各种 PDF 生成代码示例 的全面文档。

此外，您还可以探索来自 Iron Software 的相关软件产品，帮助您增强编码技能并满足现代应用需求。

Jacob Mellor，Team Iron 的首席技术官
Jacob Mellor
首席技术官

Jacob Mellor 是 Iron Software 的首席技术官，也是一位开创 C# PDF 技术的有远见的工程师。作为 Iron Software 核心代码库的原始开发者，他从公司成立之初就开始塑造公司的产品架构，与首席执行官 Cameron Rimington 一起将公司转变为一家拥有 50 多名员工的公司，为 NASA、特斯拉和全球政府机构提供服务。

相关文章

Key in blue circle

立即获取免费的 30 天试用版密钥。

Your trial license will be sent to your email address

无任何限制。100% 解锁。无需信用卡。

OR
bullet_checked无需信用卡或创建账户无任何限制。100% 解锁。无需信用卡。
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried Iron Suite
预约您的免费现场演示
Booking Badge

深受全球数百万工程师信赖

Iron Software 的客户徽标
获取您的无义务咨询
填写下面的表格或通过sales@ironsoftware.com
您的资料将始终保密。
深受全球数百万工程师信赖
Iron Software 的客户徽标
立即获取您的免费30 天试用密钥。
无需信用卡或创建账户
C# 用于 PDF 的 NuGet 库
通过 NuGet 安装

版本: 2026.9

PM > Install-Package IronPdf
nuget.org/packages/IronPdf/
  1. 在解决方案资源管理器中，右键点击引用，管理 NuGet 包
  2. 选择浏览并搜索 “IronPDF”
  3. 选择包并安装
C# PDF DLL
下载 DLL

版本: 2026.9

或在此处下载 Windows 安装程序。

  1. 下载并解压 IronPDF 到您的解决方案目录中的 ~/Libs 之类的位置
  2. 在 Visual Studio 解决方案资源管理器中，右键点击引用。选择浏览，“IronPDF.dll”

$999 起