最近我们团队一直进行.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

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

转载于:https://www.cnblogs.com/jjg0519/p/7253491.html

Asp.net core WebApi 使用Swagger生成帮助页实例相关推荐

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

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

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

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

  3. .net core webapi 通过swagger生成说明文档

    1.通过nuget安装 Swashbuckle.AspNetCore 2.startup.cs=>ConfigureServices,注册swagger 3.configure中添加: app. ...

  4. .net core WebApi 使用Swagger生成API文档

    关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因: Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API. S ...

  5. Asp.Net Core WebAPI使用Swagger时API隐藏与分组

    1.前言 为什么我们要隐藏部分接口? 因为我们在用swagger代替接口的时候,难免有些接口会直观的暴露出来,比如我们结合Consul一起使用的时候,会将健康检查接口以及报警通知接口暴露出来,这些接口 ...

  6. ASP.NET Core WebApi构建API接口服务实战演练

    一.ASP.NET Core WebApi课程介绍 人生苦短,我用.NET Core!提到Api接口,一般会想到以前用到的WebService和WCF服务,这三个技术都是用来创建服务接口,只不过Web ...

  7. 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档

    Swagger是一个描述RESTful的Web API的规范和框架.如果使用ASP.NET的话,可以用Swashbuckle来自动生成Swagger,具体参考如何使 WebAPI 自动生成漂亮又实用在 ...

  8. ASP.NET CORE WEBAPI文件下载

    最近要使用ASP.NET CORE WEBAPI用来下载文件,使用的.NET CORE 3.1.考虑如下场景: 文件是程序生成的. 文件应该能兼容各种格式. 浏览器可以感知进行下载. 准备 经过简单的 ...

  9. asp.net core WebAPI实现CRUD

    本节用于构建一个简单的WebAPI来管理to-do列表.不会创建用户界面. API Description Request body Response body GET /api/todo Get a ...

  10. IIS部署asp.net core webapi

    一.需要安装Windows Server Hosting,作用是让IIS有方向代理功能(Asp.Net Core Module负责反向代理工作),将请求转发到Kestrel,Windows serve ...

最新文章

  1. 最新离婚大数据曝光：所有的分手，都是蓄谋已久
  2. 【转】Android 快捷方式的创建
  3. Logistic Regression（逻辑回归）原理及公式推导
  4. 成功解决pywintypes.com_error: (-2147221005, '无效的类字符串', None, None)
  5. 单片机入门学习笔记7：人机交互界面
  6. web前端入门学习 css（3）（背景相关）
  7. i 智慧 | 回首30年存储演进之路 再看新数据时代阿里云存储如何革故鼎新？
  8. mysql存放lng lat_使用空间点类型在MySQL中存储Lat Lng值
  9. 字典的定义、字典的特性（成员操作符）
  10. Android触控屏幕Gesture(GestureDetector和SimpleOnGestureListener的使用教程) 分类：Androidandroid实例...
  11. vue 判断权限过期_vue 路由权限
  12. 讲道理 | 三维高斯积分公式
  13. 什么是华为认证？华为技术认证工程师可以做什么？
  14. osip 修改适用于28181和35114
  15. NOIP2015斗地主
  16. python开发面试自我介绍_面试中怎样做一个精彩的自我介绍
  17. linux 串口发送 内核,使用串口线真机调试Linux内核
  18. 为potplayer播放器添加实时中文字幕
  19. 《Linux内核情景分析》阅读笔记
  20. 【不忘初心】Windows11_22000.593_X64_无更新[深度精简版][1.37G](2022.4.2)

热门文章

  1. 2019年10月全国程序员工资统计，一半以上的职位5个月没招到人~
  2. python编程学习笔记_python学习笔记--python编程基础
  3. wxpython窗口固定大小_调整wxPython窗口的大小
  4. Python 爬取电影街美剧网址
  5. mysql 5.7 root 修改密码_Mysql5.7忘记root密码及mysql5.7修改root密码的方法
  6. python 安装pandas_Python安装的正确姿势(视频教程)(pip命令安装Pandas、Numpy、jupyter)...
  7. 屏幕共享软件开发_工作生活离不开软件，你知道什么是免费软件与共享软件吗？...
  8. oracle数据库SQL防止超长,SQL Server和Oracle防止数据锁定的比较
  9. python2020个税_2020年你会算个人所得税吗？没关系，python脚本帮助你！
  10. 最大后验估计与共轭分布