提示:文章写完后,目录可以自动生成,如何生成可参考右边的帮助文档
文章目录
- 前言
- [一、创建Web API项目](#一、创建Web API项目)
- 二、配置Swagger
- 总结
前言
".NET 7" 是指.NET 平台的第七个主要版本,是微软开发的一个跨平台应用开发框架。
一、创建Web API项目
-
在VS 2022中 选择
ASP .NET Core Web API 项目
进行创建,填写项目名称和解决方案名称,点击 "下一步"
-
勾选
启用 OPenAPI 支持
以及使用控制器
两项
-
项目启动,可以看到 Swagger 已经成功运行出来了
二、配置Swagger
1.注释配置
我们在代码通常会对api接口注释,而这部分注释也希望能通过Swagger展示出来,应该如何做呢
(1) 通过NuGet包管理器安装Swashbuckle.AspNetCore
包(创建项目时默认已添加,无需再次安装)
(2)配置Swagger生成器:在Program.cs文件中,添加以下代码以配置
bash
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "Web API", Version = "v1" });
});
- 启用Swagger中间件
bash
app.UseSwagger();
app.UseSwaggerUI(c => {
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Web API V1");
});
- 在控制器的操作方法上添加注释:在控制器操作方法上,添加XML注释以描述该方法
bash
/// <summary>
/// This is a sample operation with XML comments
/// </summary>
/// <response code="200">Success</response>
[HttpGet(Name = "GetWeatherForecast")]
- 在项目 " 属性" 中启用XML文档生成,将XML文档文件包含到Swagger配置中
如果不配置生成API文档的文件
,则Swagger UI 会报错
- 配置Swagger显示注释:在Swagger配置中将XML文档文件包含在注释中,以便Swagger可以读取和显示XML
bash
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
// Configure Swagger to use the XML documentation file generated by Visual Studio
var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
- 配置完成,重新生成项目,此时可以看到在 关于 GetWeatherForecast接口注释 已经在 " Swagger UI" 中成功显示了
总结
以上就是今天要讲的内容,本文通过以上步骤,可以配置Swagger以显示.NET代码中的接口注释。希望这些说明可以帮助您实现您的目标。如果您需要进一步的帮助,请随时告诉我。