最近我们团队一直进行.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 方法中,添加如下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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() 前面:

1
2
3
4
5
6
7
8
9
// 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 代码如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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 代码段,在最后添加如下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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 core WebApi 使用Swagger生成帮助页实例的更多相关文章

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

    最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效 ...

  2. ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

  3. ASP.NET Core WebApi使用Swagger生成api

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

  4. ASP.NET Core WebApi使用Swagger生成api说明文档

    1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...

  5. 【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...

  6. ASP.NET Core WebApi使用Swagger生成API说明文档【xml注释版】

    ⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...

  7. ASP.NET Core WebApi使用Swagger生成API说明文档【特性版】

    ⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...

  8. 三分钟学会 ASP.NET Core WebApi使用Swagger生成api说明文档

    什么是Swagger?为啥要用Swagger? Swagger可以从不同的代码中,根据注释生成API信息,Swagger拥有强大的社区,并且对于各种语言都支持良好,有很多的工具可以通过swagger生 ...

  9. Asp.net Core WebApi 使用Swagger做帮助文档,并且自定义Swagger的UI

    WebApi写好之后,在线帮助文档以及能够在线调试的工具是专业化的表现,而Swagger毫无疑问是做Docs的最佳工具,自动生成每个Controller的接口说明,自动将参数解析成json,并且能够在 ...

随机推荐

  1. Spring Boot 2 启动时加载properties文件

    每个项目从开发到测试再到上线所需要的各种环境是不同的,这就需要维护相应的配置文件,比如properties或yml文件.有了配置文件后就要考虑如何与应用进行集成. 对于云环境来讲,项目发布需要打成镜像 ...

  2. VS动态修改App.config中遇到的坑(宿主进程问题)

    昨天遇到了很奇怪的一个bug,具体描述如下: 这个系统是c/s架构的针对多个工厂做的资材管理系统,由于有很多个工厂,每个工厂都有自己的服务器.所以需要动态的改变连接字符串去链接不同的服务器. 由于这个 ...

  3. Oracle.ManagedDataAccess.Client.OracleException:“ORA-00936: 缺失表达式”

    static void Main(string[] args) { string sql = "insert into StudentC(Stuid, Stuname, Stupass) v ...

  4. C/C++掌握技能(二)

    多组输入:

  5. jQuery基础(2)

    一.jQuery的属性操作 jQuery的属性操作分为四部分: html标签属性操作:是对html文档中的标签属性进行读取,设置和移除操作.比如attr().removeAttr(): DOM属性操作 ...

  6. Docker Compose模板文件介绍

    模板文件是使用 Compose 的核心,涉及到的指令关键字也比较多,这里面大部分指令跟 docker run 相关参数的含义都是类似的.默认的模板文件名称为 docker-compose.yml ,格 ...

  7. C#6.0语言规范(十二) 数组

    数组是一种数据结构,包含许多通过计算索引访问的变量.包含在数组中的变量(也称为数组的元素)都是相同的类型,这种类型称为数组的元素类型. 数组具有确定与每个数组元素相关联的索引数的等级.数组的等级也称为 ...

  8. 传染病传播模型(SIS)Matlab代码

    function spreadingability=sir(A,beta,mu) for i=1:length(A) for N=1:50%随机次数 InitialState=zeros(length ...

  9. AndroidStudio打包apk,安装出现签名冲突--解决办法

    Android UiAutomator2项目部署到jenkins上,实现自动打包,并自动push&安装到设备上 遇到问题: 可成功实现自动打包并push到设备上后,install -r 的时候 ...

  10. C# 多线程六之Task(任务)二

    前面介绍了Task的由来,以及简单的使用,包括开启任务,处理任务的超时.异常.取消.以及如果获取任务的返回值,在回去返回值之后,立即唤起新的线程处理返回值.且如果前面的任务发生异常,唤起任务如果有效的 ...