本文共 2465 字，大约阅读时间需要 8 分钟。

Swagger 实用指南

Swagger是一种强大的工具，能够帮助开发者自动生成接口文档、进行可视化测试以及管理API信息。通过本文，你将了解如何快速入门Swagger，并在项目中实现实际应用。

什_CONN_SWAGGER

Swagger（现已更名为 OpenAPI Tooling 项目）是一种基于 Swagger 标准的接口文档生成工具。通过代码注释， Swagger 可以自动生成一套完整的 API 文档，包含接口信息、示例请求和响应。此外， Swagger 还提供了浏览器友好的可视化界面，便于开发者测试和理解 API 接口。

为何使用 Swagger

传统上，生成接口文档需要手动编写，工作量较大且易出错。在开发复杂的 API 系统时，接口文档与实际代码间的版本不匹配问题十分常见。 Swagger 能够通过分析代码，自动生成接口文档，减少了手动维护的工作量。此外， Swagger 提供了多功能工具：

• 在线测试：可以直接在文档页面发送请求测试 API。
• 多人协作：允许多个开发者同时编辑接口文档。
• 自动化文档生成：无需担心文档与代码不一致的问题。

初步尝试 Swagger

1. 安装 Swagger 包

首先，为你的 .NET Core 项目添加 Swagger 相关功能。打开 NuGet 包管理器，搜索并安装以下包：

• Microsoft.OpenApi
• Microsoft.OpenApi.Extensions
• Swashbuckle.AspNetCore.SwaggerUI

安装完成后，你的项目中就包含了 Swagger 的必要组件。

2. 配置 Swagger 服务

在 Startup.cs 文件中，修改 ConfigureServices 方法：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "Swagger 示例接口",
            Version = "v1",
            Description = "基于 Swagger 的 API 文档示例"
        });
        options.CustomSchemaIds(type => type.FullName);
        options.IncludeXmlComments(Path.Combine(Directory.GetCurrentDirectory(), "swagger_demo.xml"));
        options.DescribeAllEnumsAsStrings();
    });
}

3. 注册 Swagger UI

在 Configure 方法中注册 Swagger UI：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseCors(builder => builder.AllowAnyOrigin());
    app.UseHttpsRedirection();
    app.UseSwagger(c =>
    {
        c.RouteTemplate = "swagger/{documentName}/swagger.json";
    });
    app.UseSwaggerUI(options =>
    {
        options.ShowExtensions();
        options.ValidatorUrl(null);
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger 示例接口");
        options.DocExpansion(DocExpansion.None);
    });
    app.UseRouting();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

4. 项目设置

在项目属性中，确保生成的 swagger_demo.xml 文件路径正确。你只需右键项目名称，进入属性页，点击“生成”。在输入路径中保留默认的项目路径，确保 XML 文件名与项目代码一致。

5. 生成事件

点击右侧的“生成事件”按钮，选择“新建生成事件”。在命令行中添加：

copy $(TargetDir)swagger_demo.xml $(ProjectDir)swagger_demo.xml

6. 测试 Swagger UI

完成以上配置后，启动项目，打开浏览器访问：

http://localhost:5001/swagger

你将看到 Swagger 的美观界面，其中清晰展示了所有 API 接口的信息，包括请求示例、响应示例和接口详细文档。

通过这些步骤，你已经成功集成了 Swagger，对项目进行了全面接口文档的生成和可视化。 Swagger 的强大功能将显著提升你的开发效率，并减少文档与代码不一致的问题。