一、什么是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");
}); 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

如下图所示:

这样就可以看到接口了。但这样还不是我们最终想要的结果,我们想知道每个方法的注释和方法参数的注释,这就需要对接口做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";
} /// <summary>
/// 新增学生
/// </summary>
[HttpPost]
public void Post()
{ } /// <summary>
/// 修改学生信息
/// </summary>
[HttpPut]
public void Put()
{ } /// <summary>
/// 删除学生信息
/// </summary>
[HttpDelete]
public void Delete()
{ }
}
}

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

在运行程序:

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

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

运行程序:

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

这时会变成Cancel,点击Cancel会回到Try it out:

我们点击Execute执行:

下面会列出执行结果:

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

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

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

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

三、总结

上面简单介绍了什么是Swagger,以及如何利用Swagger进行调试,这样只需要启动程序即可,不需要在额外的使用Postman进行测试。使用Swagger可以保持接口文档能够及时更新。

ASP.NET Core 3.1使用Swagger的更多相关文章

  1. asp.net core web api 生成 swagger 文档

    asp.net core web api 生成 swagger 文档 Intro 在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果 ...

  2. Asp.Net Core Web Api 使用 Swagger 生成 api 说明文档

    最近使用 Asp.Net Core Web Api 开发项目服务端.Swagger 是最受欢迎的 REST APIs 文档生成工具之一,进入我的视野.以下为学习应用情况的整理. 一.Swagger 介 ...

  3. ASP.NET Core WebAPI帮助页--Swagger简单使用1.0

    1.什么是Swagger? Swagger是一个规范且完整的框架,提供描述.生产.消费和可视化RESTful API,它是为了解决Web API生成有用文档和帮助页的问题.   2.为啥选用swagg ...

  4. asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档

    asp.net core中使用Swashbuckle.AspNetCore(swagger)生成接口文档 Swashbuckle.AspNetCore:swagger的asp.net core实现 项 ...

  5. Asp.Net Core WebApi中接入Swagger组件(初级)

    开发WebApi时通常需要为调用我们Api的客户端提供说明文档.Swagger便是为此而存在的,能够提供在线调用.调试的功能和API文档界面. 环境介绍:Asp.Net Core WebApi + S ...

  6. Asp.Net Core 轻松学-利用 Swagger 自动生成接口文档

    前言     目前市场上主流的开发模式,几乎清一色的前后端分离方式,作为服务端开发人员,我们有义务提供给各个客户端良好的开发文档,以方便对接,减少沟通时间,提高开发效率:对于开发人员来说,编写接口文档 ...

  7. asp.net core 2.1 生成swagger文档

    新建asp.netcore2.1 api项目 “WebApplication1” 在nuget管理器中添加对Swashbuckle.AspNetCore 3.0.0.Microsoft.AspNetC ...

  8. Asp.Net Core 3.1 集成Swagger

    引入Nuget包 Swashbuckle.AspNetCore.SwaggerGen Swashbuckle.AspNetCore.SwaggerUI 配置Startup 配置ConfigureSer ...

  9. ASP.NET Core 3.1使用Swagger API接口文档

    Swagger是最流行的API开发工具,它遵循了OpenAPI规范,可以根据API接口自动生成在线文档,这样就可以解决文档更新不及时的问题.它可以贯穿于整个API生态,比如API的设计.编写API文档 ...

随机推荐

  1. Ubuntu16.04配置静态ip

    1.安装好ubuntu16.04虚拟机之后,首先按照下图的步骤进行: 首先需要打开虚拟网络编辑器,点击VMnet8的虚拟网卡,如果没有这个网卡,只需在编辑虚拟机设置里面将网络适配器类型改为NAT模式, ...

  2. linux系统下oracle表空间占用情况

    1.我们先查询表空间的占用情况,使用sql如下: select upper(f.tablespace_name) "表空间名", d.tot_grootte_mb "表空 ...

  3. MySQL数据库入门学习

    一. 前言 作为一名大二在校生,因为正在学习网页设计,考虑到后台问题,所以便自学了数据库,可能给大家总结的不是很全,但是一些必要的点肯定会讲到.现在市场上有很多图形化的数据库, 二. MySQL基础知 ...

  4. Springboot核心注解

    运行文中的代码需要在项目构建中引入springboot 相关依赖. ① @configuration configuration,用来将bean加入到ioc容器.代替传统xml中的bean配置.代码示 ...

  5. Windows下django项目部署 通过Apache2.4+mod_wsgi

    经过几天踩坑,记录在Windows10下通过Apache2.4部署Django项目的过程 运行环境: 先说下环境,怎么安装倒是其次的,版本很重要,我是根据mod_wsgi的版本要求下载的各个版本(py ...

  6. Linux之【GNU】、【GPL】、【linux系统组成】

    GNU,什么是GNU GNU全称:GNU's not unix GNU的重要组件(Emacs,gcc,bash,gawk等)加上自己的内核构成了GNU自己的系统--->没用 现在linux中的一 ...

  7. 转:Python2字符编码问题汇总

    这篇文章的部分问题在Python3以后不再存在,老猿只是觉得文章的部分内容还是有参考价值,因此在此原文转发连接: Python2字符编码问题汇总

  8. web文件包含

    web安全~文件包含总结   文章来自freebuf,作者总结的很好,所以拿来做笔记用!!! 0×01 文件包含简介 服务器执行PHP文件时,可以通过文件包含函数加载另一个文件中的PHP代码,并且当P ...

  9. 笔试题.NET基础代码面试题

    题目如下,本随笔只是记录,都是一些自身面经的题目,您既然点开了的话,学习下无妨,说不定有帮助呢 以下答案都经过博主一个个去运行过. 题目1 (实例化后 x=?;y=? 输出什么): public cl ...

  10. Centos7网卡绑定的方法

    温和的方式请参考:https://www.cnblogs.com/zzf0305/p/9594093.html 一:传统的bond方式(饭已验证)------------本种的绑定方式比较暴躁 (1) ...