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

安装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.basedirectory, 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说明信息。

在配置swagger服务时，添加安全定义可以让你为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的要求构造正确的请求体结构，并填入相应的值。

设置请求头：如果api需要特定的请求头信息，如authorization、content-type等，在swagger ui中找到“请求头”或类似的区域，添加相应的请求头名称和值。例如，如果api需要进行身份验证，可能需要在这里添加authorization头，并设置其值为有效的令牌。

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

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

调试api

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