ASP.NET Core 3.1使用Swagger

利川骆驼户外 發表於 2020-3-6 22:09:00

<h1 style="background: rgba(43, 102, 0, 1); border-radius: 6px; box-shadow: 0 0 1px rgba(95, 90, 75, 1), 1px 1px 6px 1px rgba(10, 10, 0, 0.5); color: rgba(255, 255, 255, 1)">一、什么是Swagger</h1>
随着技术的不断方法，现在的网站开发基本都是使用前后端分离的模式，这样使前端开发者和后端开发者只需要专注自己擅长的即可。但这种方式会存在一种问题：前后端通过API接口的方式进行调用，接口文档的好坏可以决定开发的进度。以前如果使用Word的形式提供接口文档，或多或少的都会存在各种问题。前端抱怨说后端给的接口文档与实际情况不一致。而后端开发人员又觉得编写以及维护接口文档很费精力，文档经常不能及时更新，导致前端看到的还是旧的接口文档。这时候就需要使用Swagger了。
那么什么是Swagger呢？Swagger是最流行的API开发工具，它遵循了OpenAPI规范，可以根据API接口自动生成在线文档，这样就可以解决文档更新不及时的问题。它可以贯穿于整个API生态，比如API的设计、编写API文档等。而且Swagger还是一种通用的、与具体编程语言无关的API描述规范。
有关更多Swagger的介绍，可以参考Swagger官网，官网地址：https://swagger.io/
<h1 style="background: rgba(43, 102, 0, 1); border-radius: 6px; box-shadow: 0 0 1px rgba(95, 90, 75, 1), 1px 1px 6px 1px rgba(10, 10, 0, 0.5); color: rgba(255, 255, 255, 1)">二、ASP.NET Core中使用Swagger</h1>
这里使用最新的ASP.NET Core 3.1创建WebAPI接口。关于如何创建WebAPI这里不在描述。创建后的WebAPI项目结构如下：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306093831178-1657967112.png">
<h2 style="background: rgba(43, 102, 149, 1); border-radius: 6px; box-shadow: 0 0 1px rgba(95, 90, 75, 1), 1px 1px 6px 1px rgba(10, 10, 0, 0.5); color: rgba(255, 255, 255, 1)">1、添加Swagger</h2>
直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306094130228-1824511447.png">
<h2 style="background: rgba(43, 102, 149, 1); border-radius: 6px; box-shadow: 0 0 1px rgba(95, 90, 75, 1), 1px 1px 6px 1px rgba(10, 10, 0, 0.5); color: rgba(255, 255, 255, 1)">2、添加服务</h2>
在Startup类的ConfigureServices方法里面注入服务：
<div class="cnblogs_code">
<pre>public void ConfigureServices(IServiceCollection services)
{
// 添加Swagger
services.AddSwaggerGen(c =>
{
 c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
});
services.AddControllers();
}</pre>
</div>
<h2 style="background: rgba(43, 102, 149, 1); border-radius: 6px; box-shadow: 0 0 1px rgba(95, 90, 75, 1), 1px 1px 6px 1px rgba(10, 10, 0, 0.5); color: rgba(255, 255, 255, 1)">3、添加中间件</h2>
在Startup类的Configure方法里面添加Swagger有关的中间件：
<div class="cnblogs_code">
<pre>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();
});
} </pre>
</div>
<h2 style="background: rgba(43, 102, 149, 1); border-radius: 6px; box-shadow: 0 0 1px rgba(95, 90, 75, 1), 1px 1px 6px 1px rgba(10, 10, 0, 0.5); color: rgba(255, 255, 255, 1)">4、添加控制器</h2>
新建一个控制器，里面包括基础的增删改查方法：
<div class="cnblogs_code">
<pre>using Microsoft.AspNetCore.Mvc;

namespace SwaggerDemo.Controllers
{

public class StudentController : ControllerBase
{

 public string Get()
 {
 return "Tom";
 }


 public void Post()
 {

 }


 public void Put()
 {

 }


 public void Delete()
 {

 }
}
}</pre>
</div>
运行程序，修改一下url地址：
<div class="cnblogs_code">
<pre>http://localhost:5000/swagger/index.html</pre>
</div>
如下图所示：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306173542893-254907688.png">
这样就可以看到接口了。但这样还不是我们最终想要的结果，我们想知道每个方法的注释和方法参数的注释，这就需要对接口做XML注释了。首先安装Microsoft.Extensions.PlatformAbstractions包：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306173824724-1650963241.png">
然后修改ConfigureServices方法，增加下面的方法：
<div class="cnblogs_code">
<pre>public void ConfigureServices(IServiceCollection services)
{
#region 添加Swagger
services.AddSwaggerGen(options =>
{
 options.SwaggerDoc("v1",newOpenApiInfo { 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();
}</pre>
</div>
然后给新建的接口添加注释：
<div class="cnblogs_code">
<pre>using Microsoft.AspNetCore.Mvc;

namespace SwaggerDemo.Controllers
{

/// <summary>
/// 学生控制器
/// </summary>

public class StudentController : ControllerBase
{
 /// <summary>
 /// 获取所有学生
 /// </summary>
 /// <returns></returns>

 public string Get()
 {
 return "Tom";
 }

 /// <summary>
 /// 新增学生
 /// </summary>

 public void Post()
 {

 }

 /// <summary>
 /// 修改学生信息
 /// </summary>

 public void Put()
 {

 }

 /// <summary>
 /// 删除学生信息
 /// </summary>

 public void Delete()
 {

 }
}
}</pre>
</div>
项目右键，选择属性，勾选“XML文档文件”，如下图所示：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306174723312-617776006.png">在运行程序：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306174921921-1274682562.png">
可以看到，刚才在控制器上面添加的注释信息都显示出来了。这样前端就可以直接查看接口文档了。
Swagger除了可以显示接口注释以外，还可以进行调试，以前调试都是使用Postman，我们也可以直接使用Swagger进行调试。新添加一个Student类：
<div class="cnblogs_code">
<pre>namespace SwaggerDemo
{
public class Student
{
 public int ID { get; set; }

 public string Name { get; set; }

 public int Age { get; set; }
}
}</pre>
</div>
然后新建一个集合，里面添加一些Student的数据，模拟数据库操作：
<div class="cnblogs_code">
<pre>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;
 }
}
}</pre>
</div>
然后修改Student控制器：
<div class="cnblogs_code">
<pre>using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace SwaggerDemo.Controllers
{

/// <summary>
/// 学生控制器
/// </summary>

public class StudentController : ControllerBase
{
 /// <summary>
 /// 获取所有学生
 /// </summary>
 /// <returns></returns>

 public List<Student> Get()
 {
 return DataHelper.GetStudent();
 }

 /// <summary>
 /// 新增学生
 /// </summary>
 /// <param name="entity">学生实体</param>
 /// <returns></returns>

 public List<Student> Post(Student entity)
 {
 DataHelper.ListStudent.Add(entity);
 return DataHelper.ListStudent;
 }

 /// <summary>
 /// 修改学生信息
 /// </summary>
 /// <param name="entity">学生实体</param>
 /// <returns></returns>

 public List<Student> Put(Student entity)
 {
 for (int i = 0; i < DataHelper.ListStudent.Count; i++)
 {
 if (DataHelper.ListStudent.ID == entity.ID)
 {
 DataHelper.ListStudent.Name = entity.Name;
 DataHelper.ListStudent.Age = entity.Age;
 break;
 }
 }
 return DataHelper.ListStudent;
 }

 /// <summary>
 /// 删除学生信息
 /// </summary>
 /// <param name="id">学生Id</param>
 /// <returns></returns>

 public List<Student> Delete(int id)
 {
 for (int i = 0; i < DataHelper.ListStudent.Count; i++)
 {
 if(DataHelper.ListStudent.ID == id)
 {
 DataHelper.ListStudent.Remove(DataHelper.ListStudent);
 break;
 }
 }
 return DataHelper.ListStudent;
 }
}
}</pre>
</div>
运行程序：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306215153154-126277055.png">
这时候是不能输入的，只能查看，点击右上角的“Try it out”：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306215344239-687110503.png">
这时会变成Cancel，点击Cancel会回到Try it out:
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306215838413-888004288.png">
 我们点击Execute执行：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306215433299-207041202.png">
 下面会列出执行结果：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306215546168-894887430.png">
这样就完成了GET方法的调试。这是无参数方法的调试，如果有参数的方法怎么调试呢？我们以POT方法为例。我们点开POST方法：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306220140644-81342432.png">
然后点击“Tty it out”，可以变成输入状态，输入参数，点击“Execute”按钮执行：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306220323557-869530204.png">
最后在下面就会输出结果：
<img src="https://img2020.cnblogs.com/i-beta/1033738/202003/1033738-20200306220434755-1569245347.png">
PUT和DELETE可以使用同样的方式进行测试。 
<h1 style="background: rgba(43, 102, 0, 1); border-radius: 6px; box-shadow: 0 0 1px rgba(95, 90, 75, 1), 1px 1px 6px 1px rgba(10, 10, 0, 0.5); color: rgba(255, 255, 255, 1)">三、总结</h1>
上面简单介绍了什么是Swagger，以及如何利用Swagger进行调试，这样只需要启动程序即可，不需要在额外的使用Postman进行测试。使用Swagger可以保持接口文档能够及时更新。 
来源：https://www.cnblogs.com/dotnet261010/p/12425572.html

頁: [1]

琼殿技术论坛's Archiver

ASP.NET Core 3.1使用Swagger