ASP .NET Core 学习 （.NET 9）- 创建 API项目，并配置Swagger及API 分组或版本
本系列为个人学习 ASP .NET Core学习全过程记录，基于.NET 9 和 VS2022 ，实现前后端分离项目基础框架搭建和部署，以简单、易理解为主，注重页面美观度和后台代码简洁明了，可能不会使用过多的高级语法和扩展，后续配合Uni-APP和vue2进行Web端和安卓端开发，尽量加紧进度更新，真正的入门学习，不喜勿喷，请绕走，感谢！
一、.NET 9 环境安装下载
安装Visual Studio 2022 和 .NET 9，基础操作，不多赘述，仅附链接：
.NET9微软官网下载
Visual Studio 2022 微软官网下载
二、ASP .NET Core Web API 项目创建
项目名称和路径自己写
创建完成后直接启动查看
在浏览器中输入控制台黑框程序中的http地址
http://localhost:5105/WeatherForecast
地址后面的 WeatherForecast 为项目创建后默认的自带的一个Controller，自带一个Get方法，由于创建的Web API项目是没有界面的，所以直接输入Controller的名称后会自动调用Get方法，返回数据
运行界面：
可以运行则证明运行环境等东西没问题，继续进行下一步吧
三、配置Swagger
由于.NET 9 微软将Swagger去除了，所以需要手动去添加
3.1 Nuget Swashbuckle.AspNetCore包
3.2 添加Swagger服务
在Program文件中，添加下面 region 中的代码
public class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddOpenApi();
#region 添加Swagger服务
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
#endregion
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
#region 启用 Swagger
app.UseSwagger();
app.UseSwaggerUI();
#endregion
}
app.UseAuthorization();
app.MapControllers();
app.Run();
}
}
再次运行项目，选择 http 启动，浏览器地址栏中输入：
http://localhost:5105/swagger/index.html
出现如下界面，则证明Swagger引用成功，接下来就可以做更多配置了。
3.3 Swagger 配置接口说明注解
通过给 AddSwaggerGen 中进行配置，同时勾选项目属性中的文档文件 选项即可实现接口注解显示
builder.Services.AddSwaggerGen(opt => {
string xmlPath = Path.Combine(AppContext.BaseDirectory, "WebApp_NET9.xml");// xml 名称一般和项目名称一致即可
opt.IncludeXmlComments(xmlPath);
});
完成以上配置运行项目，出现一下页面
给接口参数、类属性的注释都可显示，可自行测试
3.4 Swagger 配置接口分类或接口版本
需要在 AddSwaggerGen 和 UseSwaggerUI 中添加对应配置，同时给Controller添加ApiExplorerSettings，指定接口所属文档，配置接口分组和版本其实是一样的，只是给多个接口文档起名字，并配置接口属于哪个文档即可。
下面配置两个版本进行演示：
builder.Services.AddSwaggerGen(opt =>
{
#region 配置接口注释
string xmlPath = Path.Combine(AppContext.BaseDirectory, "WebApp_NET9.xml");// xml 名称一般和项目名称一致即可
opt.IncludeXmlComments(xmlPath);
#endregion
#region 配置接口分组或版本
opt.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "初版本 API",
Description = "初版本的API",
});
opt.SwaggerDoc("v2", new OpenApiInfo
{
Version = "v2",
Title = "第二版本 API",
Description = "第二版本的API",
});
#endregion
});
//......其余省略
app.UseSwaggerUI(opt =>
{
// v1 v2的名称对应上
opt.SwaggerEndpoint($"/swagger/v1/swagger.json","v1");
opt.SwaggerEndpoint($"/swagger/v2/swagger.json","v2");
});
给 WeatherForecastController 添加 [ApiExplorerSettings(GroupName =“v1”)]
新建一个Controller 为 PersonController，并添加 [ApiExplorerSettings(GroupName =“v2”)]
随意 给接口添加一些注释后，启动项目
出现一下内容及配置好了
3.5 Swagger 结束
Swagger的基础配置结束，其他功能需要使用的时候再查也行，同时Swagger默认的样式在接口多的时候可能会不太友好，也有一些改变样式的框架，可自行搜索。
实际项目中可能有的人仅在调试的时候用一下Swagger，需要给别人提供接口文档时，可以使用PostMan或者ApiPost等应用，可一件生成外网文档或内网文档链接，配置响应示例和字段说明等，会更友好一些。
下面是一个ApiPost的示例，自行选择吧
原文地址：https://blog.csdn.net/Bad_Shepherd/article/details/145208815
免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！