我要评论安装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，直到达到预期的效果。
总结
以上为个人经验，希望能给大家一个参考，也希望大家多多支持代码网。
发表评论