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

 更新时间:2017年04月25日 10:22:11   作者:suxin   我要评论
本篇文章主要介绍了Asp.net core WebApi 使用Swagger生成帮助页实例,具有一定的参考价值,感兴趣的小伙伴们可以参考一下。

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

 一、引入swagger Nuget包

右键点击wepapi项目的依赖项,点击管理Nuget程序包,如下图:

    

在打开的NuGet包程序管理界面,输入:Swashbuckle.AspNetCore 目前该程序包的版本为1.0.0,点击安装。

安装完后,需要在项目中的Startup.cs文件中进行配置。

二、配置Swagger

打开Startup.cs 文件,在ConfigureServices 方法中,添加如下代码:

 services.AddSwaggerGen(c =>
      {
        c.SwaggerDoc("v1", new Info
        {
          Version = "v1",
          Title = "TwBusManagement接口文档",
          Description = "RESTful API for TwBusManagement",
          TermsOfService = "None",
          Contact = new Contact { Name = "Alvin_Su", Email = "asdasdasd@outlook.com", Url = "" }
        });

        //Set the comments path for the swagger json and ui.
        var basePath = PlatformServices.Default.Application.ApplicationBasePath;
        var xmlPath = Path.Combine(basePath, "twbusapi.xml");
        c.IncludeXmlComments(xmlPath);

       // c.OperationFilter<HttpHeaderOperation>(); // 添加httpHeader参数
      });

注意上段代码的最后三行,是我们api描述文档xml的生成地址和文件名,需要在项目的属性中进行配置。如下图:

另外上图中,禁止显示警告中,添加1591 代码,可以过滤掉一些类名没有写注释的报警信息。

最后需要在Configure方法中,添加如下代码,注意下面的代码必须添加在  app.UseMvc() 前面:

 // Enable middleware to serve generated Swagger as a JSON endpoint.
      app.UseSwagger();

      // Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint.
      app.UseSwaggerUI(c =>
      {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "TwBusManagement API V1");
        c.ShowRequestHeaders();
      });

以上配置完后,就可以使用Swagger生成的帮助页面了,运行项目后,在浏览器地址 加上后缀 /swagger就可以跳转到帮助页面:

当然我们开发人员在开发项目的过程中并不想每次都要手动输入地址才能跳转到帮助页面,这样太麻烦。我们可借助visual studio 进行跳转,如下图:

打开 launchSettings.json 文件,把webapi项目的启动路径设置成 swagger。这样每次调试运行项目都会自动跳转到swagger帮助页面

三、Swagger的一些高级用法

Swagger非常强大,不仅仅是一些帮助页面信息,还可以进行api的调试。这样就可以不用借助第三方工具 如:postman,进行webapi的调试。swagger经过配置,还可以输入一些http头部信息,如权限认证信息等。下面就来讲解以下具体的配置。

首先我们需要新建一个类 HttpHeaderOperation,让该类继承IOperationFilter 接口,该接口需引入命名空间:Swashbuckle.AspNetCore.SwaggerGen,实现接口方法Apply 代码如下:

 public class HttpHeaderOperation : IOperationFilter
  {
    public void Apply(Operation operation, OperationFilterContext context)
    {
      if (operation.Parameters == null)
      {
        operation.Parameters = new List<IParameter>();
      }

      var actionAttrs = context.ApiDescription.ActionAttributes();

      var isAuthorized= actionAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));

      if (isAuthorized == false) //提供action都没有权限特性标记,检查控制器有没有
      {
        var controllerAttrs= context.ApiDescription.ControllerAttributes();

        isAuthorized= controllerAttrs.Any(a => a.GetType() == typeof(AuthorizeAttribute));
      }

      var isAllowAnonymous = actionAttrs.Any(a => a.GetType() == typeof(AllowAnonymousAttribute));

      if (isAuthorized && isAllowAnonymous == false)
      {
        operation.Parameters.Add(new NonBodyParameter()
        {
          Name = "Authorization", //添加Authorization头部参数
          In = "header",
          Type = "string",
          Required = false
        });
      }
    }
  }

然后在 Startup.cs 中的 ConfigureServices 方法,找到之前的AddSwaggerGen 代码段,在最后添加如下代码:

c.OperationFilter<HttpHeaderOperation>()

 services.AddSwaggerGen(c =>
      {
        c.SwaggerDoc("v1", new Info
        {
          Version = "v1",
          Title = "TwBusManagement接口文档",
          Description = "RESTful API for TwBusManagement",
          TermsOfService = "None",
          Contact = new Contact { Name = "Alvin_Su", Email = "alvin_su@outlook.com", Url = "" }
        });

        //Set the comments path for the swagger json and ui.
        var basePath = PlatformServices.Default.Application.ApplicationBasePath;
        var xmlPath = Path.Combine(basePath, "twbusapi.xml");
        c.IncludeXmlComments(xmlPath);

        c.OperationFilter<HttpHeaderOperation>(); // 添加httpHeader参数
      });

这样,我们允许webapi项目后,就可以输入 Authorization 头部参数了。如下图:

更多关于Swagger的用法可以参考https://github.com/domaindrivendev/Swashbuckle.AspNetCore 以及微软文档:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持脚本之家。

相关文章

  • asp.net操作过程中常见错误的解决方法

    asp.net操作过程中常见错误的解决方法

    这篇文章主要介绍了asp.net操作过程中常见错误的解决方法,主要有IIS无法识别ASP.NET、 SQL Server不允许进行远程连接可能会导致此失败等问题,感兴趣的小伙伴们可以参考一下
    2015-10-10
  • ASP.NET(C#)

    ASP.NET(C#)

    ASP.NET(C#)...
    2006-07-07
  • asp.net分割字符串的几种方法小结

    asp.net分割字符串的几种方法小结

    在编写程序中,经常要用到分割的方法来处理一些字符串。这里总结了几种常用的分割方法
    2012-01-01
  • 把字符串转为HtmlTable演示动画

    把字符串转为HtmlTable演示动画

    怎样将字符串转为.cs页面中的HtmlTable,在论坛上看到了这样一个问题,想试着把它解决下,感兴趣的朋友可以观看下本文的动画,或许对你有所帮助
    2013-03-03
  • ASP.NET实现进度条效果

    ASP.NET实现进度条效果

    这篇文章主要为大家详细介绍了ASP.NET实现简单的进度条效果,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2017-06-06
  • MvcPager分页控件使用注意事项

    MvcPager分页控件使用注意事项

    这篇文章主要为大家详细介绍了MvcPager分页控件使用的注意事项,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2017-06-06
  • 用ASP.NET还原与恢复Sql server

    用ASP.NET还原与恢复Sql server

    用ASP.NET还原与恢复Sql server...
    2006-09-09
  • ASP.NET Core与NLog集成的完整步骤

    ASP.NET Core与NLog集成的完整步骤

    NLog是一个免费的日志记录框架,专门为.net平台下的框架提供日志功能,下面这篇文章主要给大家介绍了关于ASP.NET Core与NLog集成的相关资料,文中通过示例代码介绍的非常详细,需要的朋友可以参考下
    2018-07-07
  • asp.net编程获取项目根目录实现方法集合

    asp.net编程获取项目根目录实现方法集合

    这篇文章主要介绍了asp.net编程获取项目根目录实现方法,结合实例形式分析总结了asp.net针对项目目录的操作技巧与注意事项,需要的朋友可以参考下
    2015-11-11
  • 详解VS2012发布网站步骤

    详解VS2012发布网站步骤

    这篇文章主要以图文相结合的方式介绍了VS2012发布网站的详细步骤,需要了解的朋友可以参考下
    2015-08-08

最新评论