ASP.NET Core 3.1使用Swagger - 栀子味的四月

一、什么是Swagger

随着技术的不断方法，现在的网站开发基本都是使用前后端分离的模式，这样使前端开发者和后端开发者只需要专注自己擅长的即可。但这种方式会存在一种问题：前后端通过API接口的方式进行调用，接口文档的好坏可以决定开发的进度。以前如果使用Word的形式提供接口文档，或多或少的都会存在各种问题。前端抱怨说后端给的接口文档与实际情况不一致。而后端开发人员又觉得编写以及维护接口文档很费精力，文档经常不能及时更新，导致前端看到的还是旧的接口文档。这时候就需要使用Swagger了。

那么什么是Swagger呢？Swagger是最流行的API开发工具，它遵循了OpenAPI规范，可以根据API接口自动生成在线文档，这样就可以解决文档更新不及时的问题。它可以贯穿于整个API生态，比如API的设计、编写API文档等。而且Swagger还是一种通用的、与具体编程语言无关的API描述规范。

有关更多Swagger的介绍，可以参考Swagger官网，官网地址：https://swagger.io/

二、ASP.NET Core中使用Swagger

这里使用最新的ASP.NET Core 3.1创建WebAPI接口。关于如何创建WebAPI这里不在描述。创建后的WebAPI项目结构如下：

1、添加Swagger

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

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");
});
}

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:运行的端口号/swagger/index.html

如下图所示：

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

然后修改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";
    }
}
}

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

或者是：

在运行程序：

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

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

namespace WebApplication2.Models
{
public class User
{
public int userId { get; set; }
public string account { get; set; }
public string userName { get; set; }
public string passWord { get; set; }
public int age { get; set; }
public string email { get; set; }
public string redirectUrl { get; set; }
 }
}

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

using System;
using System.Collections.Generic;
using System.IO;
using System.Security.Cryptography;
using System.Text;
using WebApplication2.Models;

namespace WebApplication2.Core
{
    public class AESHelper
    {
        public  List<User> ListStudent = new List<User>();
        public  List<User> GetStudent()
        {
            for (int i = 0; i < 5; i++)
            {
                User student = new User();
                student.userId = i;
                student.userName = $"测试_{i}";
                student.age = 20 + i;
                ListStudent.Add(student);
            }
            return ListStudent;
        }
  
    }
}

然后修改Swagger控制器：

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using WebApplication2.Core;
using WebApplication2.Models;

namespace WebApplication2.Controllers
{
    [Route("[controller]/[action]")]
    [ApiController]
    public class SwaggerController : ControllerBase
    {
        /// <summary>
        /// 获取所有用户信息
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public List<User> GetUserList() 
        {
            return new AESHelper().GetStudent();
        }

        /// <summary>
        /// 新增学生
        /// </summary>
        /// <param name="entity">学生实体</param>
        /// <returns></returns>
        [HttpPost]
        public List<User> PostUser(User entity)
        {
            List<User> ListStudent = new List<User>();
            for (int i = 0; i < 5; i++)
            {
                User student = new User();
                student.userId = i;
                student.userName = $"测试_{i}";
                student.age = 20 + i;
                ListStudent.Add(student);
            }
            ListStudent.Add(entity);
            // new AESHelper().ListStudent.Add(entity);
            return ListStudent;
        }

        /// <summary>
        /// 获取姓名
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public string Get()
        {
            return "Tom";
        }
        /// <summary>
        /// post方法
        /// </summary>
        [HttpPost]
        public void Post()
        {
        }
        /// <summary>
        /// put方法
        /// </summary>
        [HttpPut]
        public void Put()
        {
        }
        /// <summary>
        /// delete方法
        /// </summary>
        [HttpDelete]
        public void Delete()
        {
        }
    }
}

运行程序：