C#项目中引用Swagger的详细步骤和配置方式

目录

• 安装Swagger相关包
• 配置Swagger服务
• 启用Swagger中间件
• 验证Swagger是否配置成功
• 对特定API添加注释和描述
• JWT认证安全定义
• API密钥认证安全定义
• 准备工作
• 测试API
• 调试API
• 总结

安装Swagger相关包

打开你的C#项目解决方案，在Visual Studio中，右键点击项目名称，选择“管理NuGet程序包”。

在NuGet包管理器中，搜索以下包并进行安装：

• Swashbuckle.ASPNetCore：这是Swagger用于ASP.NET Core的主要库，它包含了生成Swagger文档和提供Swagger UI的功能。
• Microsoft.OpenApi.Models：提供了OpenAPI规范的模型定义，Swashbuckle.AspNetCore会使用这些模型来生成Swagger文档。

配置Swagger服务

• 在项目的Startup.cs文件中，找到ConfigureServices方法，在其中添加以下代码来配置Swagger服务：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public void ConfigureServices(IServiceCollection services)
{
    // 其他服务配置...

    // 添加Swagger生成器服务
    services.AddSwaggerGen(c =>
    {
        // 定义Swagger文档信息
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Version = "v1",
            Title = "Your API Title",
            Description = "Your API description",
            TermsOfService = new Uri("https://example.com/terms"),
            Contact = new OpenApiContact
            {
                Name = "Contact Name",
                Email = "contact@example.com",
                Url = new Uri("https://example.com/contact")
            },
            License = new OpenApiLicense
            {
                Name = "License Name",
                Url = new Uri("https://example.com/license")
            }
        });

        // 配置XML注释文件路径，以便在Swagger文档中显示方法注释等信息
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirect编程客栈ory, xmlFile);
        c.IncludeXmlComments(xmlPath);

        // 如果你的API有身份验证等安全机制，可以在这里配置
        c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
        {
            In = ParameterLocation.Header,
            Description = "Please enter JWT with Bearer prefix",
            Name = "Authorization",
            Type = SecuritySchemeType.ApiKey
        });
        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                },
                new string[] {}
            }
        });
    });
}

• 上述代码中，首先通过AddSwaggerGen方法添加了Swagger生成器服务，并定义了Swagger文档的基本信息，如版本、标题、描述等。然后配置了XML注释文件的路径，这样Swagger会根据XML注释生成更详细的文档内容。最后，配置了Bearer令牌的身份验证机制。

启用Swagger中间件

• 在Startup.cs文件的Configure方法中，添加以下代码来启用Swagger中间件：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 其他中间件配置...

    // 启用Swagger
    app.UseSwagger();

    // 启用Swagger UI，指定Swagger jsON文档的路由
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API v1");
        // 如果需要，可以配置Swagger UI的其他选项，如文档展开深度等
        c.DocExpansion(DocExpansion.None);
    });
}

• 这段代码首先使用UseSwagger中间件来生成Swagger JSON文档，然后使用UseSwaggerUI中间件来提供Swagger UI界面，方便用户查看和测试API。通过SwaggerEndpoint方法指定了Swagger JSON文档的路由和显示在Swagger UI中的文档名称。

验证Swagger是否配置成功

• 运行你的C#项目，在浏览器中输入http://localhost:port/swagger，其中port是你的项目运行的端口号。
• 如果一切配置正确，你应该能够看到Swagger UI界面，其中列出了你项目中的所有API端点，并且可以查看每个端点的详细信息和进行测试。

对特定API添加注释和描述

• 为了使Swagger文档更加详细和准确，可以在控制器的方法和模型类上添加XML注释。
• 例如：

/// <summary>
/// 获取用户信息
/// </summary>
/// <param name="id">用户ID</param>
/// <returns>用户信息对象</returns>
[HttpGet("{id}")]
public IActionResult GetUser(int id)
{
    // 方法实现
}

• 这样，在Swagger UI中就可以看到更详细的API说明信息。

在配置Sjavascriptwagger服务时，添加安全定义可以让你为API指定各种安全机制，如JWT认证、API密钥认证等。以下以常见的JWT认证和API密钥认证为例，介绍如何添加安全定义：

JWT认证安全定义

添加命名空间引用

在Startup.cs文件的顶部，添加以下命名空间引用：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

在ConfigureServices方法中配置Swagger安全定义

在Startup.cs文件的ConfigureServices方法中，找到services.AddSwaggerGen(c => {})代码块，在其中添加以下代码：

// 添加Swagger生成器服务
services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...

    // 添加JWT Bearer安全定义
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        // 定义安全机制的类型为API密钥
        Type = SecuritySchemeType.ApiKey,
        // 说明该密钥位于请求头中
        In = ParameterLocation.Header,
        // 请求头中用于传递JWT令牌的字段名称
        Name = "Authorization",
        // 对该安全定义的描述，在Swagger UI中会显示给用户
        Description = "请输入带有Bearer前缀的JWT令牌"
    });

    // 添加安全要求，指定使用Bearer安全定义的API需要进行身份验证
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                // 引用前面定义的Bearer安全定义
                Reference = new OpenApiReference
     编程客栈           {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            // 这里可以指定一些额外的作用域或权限，如果不需要可以留空数组
            new string[] { }
        }
    });
});

上述代码首先使用AddSecurityDefinition方法添加了名为Bearer的安全定义，指定了安全机制为API密钥，位于请求头的Authorization字段中，并给出了描述。然后使用AddSecurityRequirement方法指定了使用Bearer安全定义的API需要进行身份验证。

API密钥认证安全定义

添加命名空间引用

同样在Startup.cs文件的顶部，添加与JWT认证安全定义时相同的命名空间引用：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

在ConfigureServices方法中配置Swagger安全定义

在Startup.cs文件的ConfigureServices方法中，找到services.AddSwaggerGen(c => {})代码块，在其中添加以下代码：

// 添加Swagger生成器服务
services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...

    // 添加API密钥安全定义
    c.AddSecurityDefinition("ApiKey", new OpenApiSecurityScheme
    {
        // 定义安全机制的类型为API密钥
        Type = SecuritySchemeType.ApiKey,
        // 说明该密钥位于请求头中
        In = ParameterLocation.Header,
        // 请求头中用于传递API密钥的字段名称
        Name = "X-Api-Key",
        // 对该安全定义的描述，在Swagger UI中会显示给用户
        Description = "请输入你的API密钥"
    });

    // 添加安全要求，指定使用ApiKey安全定义的API需要提供有效的API密钥
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                // 引用前面定义的ApiKey安全定义
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "ApiKey"
                }
            },
            // 这里可以指定一些额外的作用域或权限，如果不需要可以留空数组
            new string[] { }
        }
    });
});

上述代码添加了名为ApiKey的安全定义，指定安全机制为API密钥，位于请求头的X - Api - Key字段中，并给出了描述。同时也添加了安全要求，确保使用ApiKey安全定义的API在调用时需要提供有效的API密钥。

在Swagger中可以方便地进行API的测试和调试，以下是具体步骤：

准备工作

• 确保已在项目中成功引用并配置了Swagger，且项目能够正常运行，Swagger UI可以正常访问。

测试API

访问Swagger UI：启动项目后，在浏览器中输入Swagger UI的地址，如http://localhost:port/swagger，其中port是项目运行的端口号。进入Swagger UI界面，会看到项目中所有暴露的API列表，每个API以其定义的HTTP方法（如GET、POST、PUT、DELETE等）和路径显示。

选择要测试的API：在Swagger UI中找到想要测试的API端点。每个API端点都有对应的描述和参数信息。

填写参数：对于需要参数的API，在Swagger UI提供的参数输入区域填写相应的值。参数类型可能包括路径参数、查询参数、请求体参数等。

• 路径参数：通常在API路径中以大括号{}表示，直接在对应的输入框中输入参数值。
• 查询参数：一般在路径后面以问号?开始，多个参数之间用&连接，在Swagger UI中会有专门的输入框供填写查询参数的名称和值。
• 请求体参数：对于POST、PUT等需要发送请求体的API，在Swagger UI中通常有一个专门的区域用于输入JSON或其他格式的请求体数据。可以根据API的要求构造正确的请求体结构，并填入相http://www.devze.com应的值。

设置请求头：如果API需要特定的请求头信息，如Authorization、Content-Type等，在Swagger UI中找到“请求头&编程客栈rdquo;或类似的区域，添加相应的请求头名称和值。例如，如果API需要进行身份验证，可能需要在这里添加Authorization头，并设置其值为有效的令牌。

执行测试：填写完参数和请求头后，点击API端点旁边的“执行”或“试一下！”按钮，Swagger将发送请求到后端API。

查看响应结果：发送请求后，Swagger UI会显示API的响应结果，包括响应状态码、响应头和响应体。可以根据响应信息判断API是否正常工作，以及返回的数据是否符合预期。

调试API

• 查看请求详情：如果测试结果不符合预期，可查看请求的详细信息来帮助调试。在Swagger UI中，通常有一个“查看请求”或类似的按钮，点击后可以查看发送的完整请求信息，包括请求URL、方法、参数、请求头和请求体等，确保请求的内容与预期一致。
• 检查响应状态码：根据响应状态码判断请求的处理情况。常见的状态码如200表示请求成功，400表示客户端请求错误，401表示未授权，500表示服务器内部错误等。根据不同的状态码，可以初步确定问题所在的方向。
• 分析响应体：仔细查看响应体中的信息，可能包含错误消息、调试信息或其他有用的提示。如果响应体是JSON格式，可以使用JSON格式化工具来更清晰地查看其结构和内容。
• 结合后端日志：在调试API时，查看后端服务器的日志是非常有帮助的。后端日志可以提供更详细的信息，如请求的处理过程、出现的异常等。根据日志中的信息，可以定位到具体的代码位置，进一步分析和解决问题。
• 修改请求并重新测试：根据分析的结果，对请求参数、请求头或请求体进行修改，然后再次点击“执行”按钮，重新发送请求，观察响应结果是否有所改善。通过不断地修改和测试，逐步调试API，直到达到预期的效果。

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持编程客栈(www.devze.com)。