ASP.NET Core中使用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");
    });

    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中使用Swagger的文章就介绍到这了。希望对大家的学习有所帮助,也希望大家多多支持我们。

(0)

相关推荐

  • ASP.NetCore使用Swagger实战

    踩坑不背锅,.NET Core 试深浅 关于Swagger什么是swagger所带来的帮助 使用Swagger 关于Swagger 什么是swagger 使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能. Swagger™ 的目标是为 REST APIs 定义一个标准的,与语言无关的接口.只需要按照它的规范去定义接口及接口相关的信息.再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码

  • asp.net core 集成swagger ui的原理解析

    什么是Swagger? 说swagger 之前,我们先说一下OpenApi 规范. OpenApi 是一种和语言无关的用于描述RESTAPIs 接口功能的一种规范,对RESTAPIs 接口的描述包括: 接口参数信息.接口返回值信息.api 功能描述.请求路径等. 这里我们说OpenApi 只是一种规范,既然是一种规范,就必然有相应的实现,Swagger 就是其中一个实现了Open Api 规范的工具. .net 中RESTAPIs的代表便是 web api ,并且.net 针对Web Api 也

  • 记Asp.Net Core Swagger使用并带域接口处理的方法

    引用作者原话:Asp.Net的WebApi中使用Swagger作为说明和测试的页面是非常不错的,比起WebApiTestClient来至少在界面上的很大的提升.但是使用Swagger时如果只是一般的控制器直接放到Controller下就可以了,而如果因不同的业务需求而需要分类或者有同名的类名时时则没办法很好的处理. 因为业务需求需要创建域,但是Swagger并未将域添加到接口.所以需要加上以下操作才行. 安装Swagger方法: 为了大家多看微软官方文档.就直接引用Swagger安装及使用方法.

  • Asp.Net Core使用swagger生成api文档的完整步骤

    前言 .Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag.两者的配置大同小异.这里以NSwag为例. 一.前期准备 1.初始化asp.net core 测试项目 新建asp.net core项目,此处略过: 新建apicontroller,并编写测试代码: [Route("api/[controller]")] [ApiController] public class UserApiController : ControllerBase { ///

  • Asp.net core WebApi 使用Swagger生成帮助页实例

    最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效率低下的问题,一次在看微软asp.net core官方文档的时候,发现了swagger这个好东西.然后在实际的项目中引入了该技术.我们开发人员测试自己写的api的过程大大得到了简化,前端人员也可以根据我们提供的swagger help pages 自己进行一些前端代码的测试,大大提高了前后端的开发效

  • asp.net core 3.0中使用swagger的方法与问题

    Intro# 上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用,那个项目的 api 比较简单,都是匿名接口不涉及到认证以及 api 版本控制,最近把另外一个 api 项目升级到了 3.0,还是遇到了一些问题,这里单独写一篇文章介绍,避免踩坑. Swagger 基本使用# swagger 服务注册: services.AddSwaggerGen(option => { option.SwaggerDoc("sparktodo", new Ope

  • Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解

    1.前言 为什么我们要隐藏部分接口? 因为我们在用swagger代替接口的时候,难免有些接口会直观的暴露出来,比如我们结合Consul一起使用的时候,会将健康检查接口以及报警通知接口暴露出来,这些接口有时候会出于方便考虑,没有进行加密,这个时候我们就需要把接口隐藏起来,只有内部的开发者知道. 为什么要分组? 通常当我们写前后端分离的项目的时候,难免会遇到编写很多接口供前端页面进行调用,当接口达到几百个的时候就需要区分哪些是框架接口,哪些是业务接口,这时候给swaggerUI的接口分组是个不错的选

  • ASP.NET Core中使用Swagger

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

  • asp.net core 中优雅的进行响应包装的实现方法

    目录 摘要 正常响应包装 实现按需禁用包装 总结 摘要 在 asp.net core 中提供了 Filter 机制,可以在 Action 执行前后进行一些特定的处理,例如模型验证,响应包装等功能就可以在此基础上实现,同时也提供了 ApplicationModel API, 我们可以在此基础上实现选择性的添加 Filter,满足部分接口需要响应特定的结构, 我们常见的 [AllowAnonymous] 正是基于这种机制.同时也将介绍如何让 Swagger 展示正确的包装响应体,以满足第三方对接或前

  • ASP.NET Core中使用xUnit进行单元测试

    单元测试的功能自从MVC的第一个版本诞生的时候,就是作为一个重要的卖点来介绍的,通常在拿MVC与webform比较的时候,单元测试就是必杀底牌,把webform碾压得一无是处. 单元测试的重要性不用多说了,有单元测试的做兜底的项目,好比给开发人员买了份保险,当然这个保险的质量取决于单元测试的质量,那些一路Mock的单元测试,看起来很美,但是什么都cover不到.目前工作中的一个老项目,有2万多个单元测试用例,其中不少是用心之作,真正落实到了业务逻辑,开发人员可以放心的去修改代码,当然一切都必须按

  • 详解ASP.NET Core 中的框架级依赖注入

    1.ASP.NET Core 中的依赖注入 此示例展示了框架级依赖注入如何在 ASP.NET Core 中工作. 其简单但功能强大,足以完成大部分的依赖注入工作.框架级依赖注入支持以下 scope: Singleton - 总是返回相同的实例 Transient - 每次都返回新的实例 Scoped - 在当前(request)范围内返回相同的实例 假设我们有两个要通过依赖注入来进行工作的工件: PageContext - 自定义请求上下文 Settings - 全局应用程序设置 这两个都是非常

  • 解析Asp.net Core中使用Session的方法

    前言 2017年就这么悄无声息的开始了,2017年对我来说又是特别重要的一年. 元旦放假在家写了个Asp.net Core验证码登录, 做demo的过程中遇到两个小问题,第一是在Asp.net Core中引用dll,以往我们引用DLL都是直接引用,在Core里这样是不行的,必须基于NuGet添加,或者基于project.json添加,然后保存VS会启动还原类库. 第二就是使用Session的问题,Core里使用Session需要添加Session类库. 添加Session 在你的项目上基于NuG

  • 详解在ASP.NET Core 中使用Cookie中间件

    在 http:// ASP.NET Core 中使用Cookie中间件 ASP.NET Core 提供了Cookie中间件来序列化用户主题到一个加密的Cookie中并且在后来的请求中校验这个Cookie,再现用户并且分配到HttpContext对象的User属性中.如果你想提供自己的登录方式和用户数据你可以使用Cookie中间件来实现独立的功能. 添加和配置 第一步是增加Cookie中间件到你的应用中.首先使用nuget增加Microsoft.AspNetCore.Authentication.

  • 详解如何在ASP.NET Core中应用Entity Framework

    首先为大家提醒一点,.NET Core和经典.NET Framework的Library是不通用的,包括Entity Framework! 哪怎么办? 别急,微软为.NET Core发布了.NET Core版本的Entity Framework,具体配置方法与经典.NET Framework版本的稍有区别,下面的内容就为带领大家在ASP.NET Core中应用Entity Framework DB first. 注:目前部分工具处于Preview版本,正式版本可能会稍有区别. 前期准备: 1.推

  • 在ASP.NET Core 中发送邮件的实现方法(必看篇)

    前言 我们知道目前 .NET Core 还不支持 SMTP 协议,当我么在使用到发送邮件功能的时候,需要借助于一些第三方组件来达到目的,今天给大家介绍两款开源的邮件发送组件,它们分别是 MailKit 和 FluentEmail , 下面我对它们分别进行介绍. MailKit 在 ASP.NET Core 中,可以使用 MailKit 来发送邮件,它支持跨平台,并且支持 IMAP, POP3, SMTP 等协议. 你可以使用下面的方式安装: Install-Package MailKit 下面是

  • 浅谈如何在ASP.NET Core中实现一个基础的身份认证

    ASP.NET终于可以跨平台了,但是不是我们常用的ASP.NET, 而是叫一个ASP.NET Core的新平台,他可以跨Windows, Linux, OS X等平台来部署你的web应用程序,你可以理解为,这个框架就是ASP.NET的下一个版本,相对于传统ASP.NET程序,它还是有一些不同的地方的,比如很多类库在这两个平台之间是不通用的. 今天首先我们在ASP.NET Core中来实现一个基础的身份认证,既登陆功能. 前期准备: 1.推荐使用 VS 2015 Update3 作为你的IDE,下

  • 谈谈如何在ASP.NET Core中实现CORS跨域

    CORS(Cross-origin resource sharing)是一个W3C标准,翻译过来就是 "跨域资源共享",它主要是解决Ajax跨域限制的问题. CORS需要浏览器和服务器支持,现在所有现代浏览器都支持这一特性.注:IE10及以上 只要浏览器支持,其实CORS所有的配置都是在服务端进行的,而前端的操作浏览器会自动完成. 在本例中,将演示如何再ASP.NET Core中实现CORS跨域. 前期准备 你需要windows系统. 你需要安装IIS. 推荐使用VS2015 Upda

随机推荐