ASP.NET Core 3.1使用Swagger

红太狼 2022-12-09 03:11 145阅读 0赞

# [ASP.NET Core 3.1使用Swagger][ASP.NET Core 3.1_Swagger] #

## 1.添加swagger ##

直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装：

![41acb1dd423cc0461d1317ba9c2220d8.png][]

## 2.添加服务 ##

在Startup类的ConfigureServices方法里面注入服务：

public void ConfigureServices(IServiceCollection services)
    {
        // 添加Swagger
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
        });
        services.AddControllers();
    }

## 3.添加中间件 ##

在Startup类的Configure方法里面添加Swagger有关的中间件：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
    
        // 添加Swagger有关中间件
        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");
        });
    
        app.UseRouting();
    
        app.UseAuthorization();
    
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }

## 4、添加控制器 ##

新建一个控制器，里面包括基础的增删改查方法：

using Microsoft.AspNetCore.Mvc;
    
    namespace SwaggerDemo.Controllers
    {
        [Route("api/student")]
        [ApiController]
        public class StudentController : ControllerBase
        {
            [HttpGet]
            public string Get()
            {
                return "Tom";
            }
    
            [HttpPost]
            public void Post()
            {
                
            }
    
            [HttpPut]
            public void Put()
            {
    
            }
    
            [HttpDelete]
            public void Delete()
            {
    
            }
        }
    }

运行程序，修改一下url地址：

http://localhost:5000/swagger/index.html

如下图所示：

![52ea20477aee8d9e7cbd9f975e817ee3.png][]

这样就可以看到接口了。但这样还不是我们最终想要的结果，我们想知道每个方法的注释和方法参数的注释，这就需要对接口做XML注释了。首先安装Microsoft.Extensions.PlatformAbstractions包：

![a51d9861ae171aa433ce3b599426cf41.png][]

然后修改ConfigureServices方法，增加下面的方法：

public void ConfigureServices(IServiceCollection services)
    {
        #region 添加Swagger
        services.AddSwaggerGen(options =>
        {
            options.SwaggerDoc("v1",new  OpenApiInfo { Title = "My API", Version = "v1" });
            // 获取xml文件名
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            // 获取xml文件路径
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            // 添加控制器层注释，true表示显示控制器注释
            options.IncludeXmlComments(xmlPath, true);
        });
        #endregion
        services.AddControllers();
    }

然后给新建的接口添加注释：

using Microsoft.AspNetCore.Mvc;
    
    namespace SwaggerDemo.Controllers
    {
    
        /// <summary>
        /// 学生控制器
        /// </summary>
        [Route("api/student")]
        [ApiController]
        public class StudentController : ControllerBase
        {
            /// <summary>
            /// 获取所有学生
            /// </summary>
            /// <returns></returns>
            [HttpGet]
            public string Get()
            {
                return "Tom";
            }
    
            /// <summary>
            /// 新增学生
            /// </summary>
            [HttpPost]
            public void Post()
            {
                
            }
    
            /// <summary>
            /// 修改学生信息
            /// </summary>
            [HttpPut]
            public void Put()
            {
    
            }
    
            /// <summary>
            /// 删除学生信息
            /// </summary>
            [HttpDelete]
            public void Delete()
            {
    
            }
        }
    }

项目右键，选择属性，勾选“XML文档文件”，如下图所示：

（这个文件路径是可以写相对路径比如：\\bin\\Debug\\netcoreapp3.1\\HimCloud.xml）

![148edd62d76d7e64bdf4eb7e2dfa2d74.png][]

在运行程序：

![3d9fc47e6f200e1cbe4df84fbdb7fbcc.png][]

可以看到，刚才在控制器上面添加的注释信息都显示出来了。这样前端就可以直接查看接口文档了。

Swagger除了可以显示接口注释以外，还可以进行调试，以前调试都是使用Postman，我们也可以直接使用Swagger进行调试。新添加一个Student类：

namespace SwaggerDemo
    {
        public class Student
        {
            public int ID { get; set; }
    
            public string Name { get; set; }
    
            public int Age { get; set; }
        }
    }

然后新建一个集合，里面添加一些Student的数据，模拟数据库操作：

using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    
    namespace SwaggerDemo
    {
        public class DataHelper
        {
            public static List<Student> ListStudent = new List<Student>();
    
            public static List<Student> GetStudent()
            {
                for (int i = 0; i < 5; i++)
                {
                    Student student = new Student();
                    student.ID = i;
                    student.Name = $"测试_{i}";
                    student.Age = 20 + i;
                    ListStudent.Add(student);
                }
    
                return ListStudent;
            }
        }
    }

然后修改Student控制器：

using Microsoft.AspNetCore.Mvc;
    using System.Collections.Generic;
    
    namespace SwaggerDemo.Controllers
    {
    
        /// <summary>
        /// 学生控制器
        /// </summary>
        [Route("api/student")]
        [ApiController]
        public class StudentController : ControllerBase
        {
            /// <summary>
            /// 获取所有学生
            /// </summary>
            /// <returns></returns>
            [HttpGet]
            public List<Student> Get()
            {
                return DataHelper.GetStudent();
            }
    
            /// <summary>
            /// 新增学生
            /// </summary>
            /// <param name="entity">学生实体</param>
            /// <returns></returns>
            [HttpPost]
            public List<Student> Post(Student entity)
            {
                DataHelper.ListStudent.Add(entity);
                return DataHelper.ListStudent;
            }
    
            /// <summary>
            /// 修改学生信息
            /// </summary>
            /// <param name="entity">学生实体</param>
            /// <returns></returns>
            [HttpPut]
            public List<Student> Put(Student entity)
            {
                for (int i = 0; i < DataHelper.ListStudent.Count; i++)
                {
                    if (DataHelper.ListStudent[i].ID == entity.ID)
                    {
                        DataHelper.ListStudent[i].Name = entity.Name;
                        DataHelper.ListStudent[i].Age = entity.Age;
                        break;
                    }
                }
                return DataHelper.ListStudent;
            }
    
            /// <summary>
            /// 删除学生信息
            /// </summary>
            /// <param name="id">学生Id</param>
            /// <returns></returns>
            [HttpDelete]
            public List<Student> Delete(int id)
            {
                for (int i = 0; i < DataHelper.ListStudent.Count; i++)
                {
                    if(DataHelper.ListStudent[i].ID == id)
                    {
                        DataHelper.ListStudent.Remove(DataHelper.ListStudent[i]);
                        break;
                    }
                }
                return DataHelper.ListStudent;
            }
        }
    }

运行程序：

![6e2473c5f9edc6c5937ebdfad483cbbd.png][]

这时候是不能输入的，只能查看，点击右上角的“Try it out”：

![f5f632654c2211cda73cecec68360dc7.png][]

我们点击Execute执行：

![5a2cd5b378516d53ed695f113c6a9ff1.png][]

下面会列出执行结果：

![ae1e4d976913268993a6e0b0f969664f.png][]

这样就完成了GET方法的调试。这是无参数方法的调试，如果有参数的方法怎么调试呢？我们以POT方法为例。我们点开POST方法：

![4cdee0048b183427f722864bc8fc1f7c.png][]

然后点击“Tty it out”，可以变成输入状态，输入参数，点击“Execute”按钮执行：

![1126403c5dbc6be4e248312708ef8bc5.png][]

最后在下面就会输出结果：

![adcfd427fc730fcca3e9e4ee55529f4a.png][]

PUT和DELETE可以使用同样的方式进行测试。

[ASP.NET Core 3.1_Swagger]: https://www.cnblogs.com/dotnet261010/p/12425572.html
[41acb1dd423cc0461d1317ba9c2220d8.png]: /images/20221123/5f1569634c46496d943993ea71692fd5.png
[52ea20477aee8d9e7cbd9f975e817ee3.png]: /images/20221123/ce9b9e92ec3e443eb0a23aabdfa60a83.png
[a51d9861ae171aa433ce3b599426cf41.png]: /images/20221123/a12af767c8e14e55a277e19f71e749b7.png
[148edd62d76d7e64bdf4eb7e2dfa2d74.png]: /images/20221123/7dbf5039d54748648b76ac411eee602d.png
[3d9fc47e6f200e1cbe4df84fbdb7fbcc.png]: /images/20221123/6051cf93d94f4280a8a3608d30250c9b.png
[6e2473c5f9edc6c5937ebdfad483cbbd.png]: /images/20221123/5124b92552c749c393d9bdf89cf06961.png
[f5f632654c2211cda73cecec68360dc7.png]: /images/20221123/1821e1935f544b7f88396ff3b0dc6715.png
[5a2cd5b378516d53ed695f113c6a9ff1.png]: /images/20221123/674083b442da4122b427cbea982679fd.png
[ae1e4d976913268993a6e0b0f969664f.png]: /images/20221123/1a449690c37f41359ee40878770356fd.png
[4cdee0048b183427f722864bc8fc1f7c.png]: /images/20221123/aad3b3b6026b472189d37f4313972663.png
[1126403c5dbc6be4e248312708ef8bc5.png]: /images/20221123/0062b70480254b1e9ac5be06f2a4ec19.png
[adcfd427fc730fcca3e9e4ee55529f4a.png]: /images/20221123/d03e5fc621a74de1817a41d6ccb10125.png