ASP .NET Core 学习（.NET 9）- 创建 API项目，并配置Swagger及API 分组或版本

news2025/1/18 5:34:16

本系列为个人学习 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的示例，自行选择吧
在这里插入图片描述