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 core WebApi 使用Swagger生成帮助页的更多相关文章

Asp.net core WebApi 使用Swagger生成帮助页实例
最近我们团队一直进行.net core的转型,web开发向着前后端分离的技术架构演进,我们后台主要是采用了asp.net core webapi来进行开发,开始每次调试以及与前端人员的沟通上都存在这效 ...
ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
引言在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...
ASP.NET Core WebApi使用Swagger生成api
引言在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...
ASP.NET Core WebApi使用Swagger生成api说明文档
1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...
【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...
ASP.NET Core WebApi使用Swagger生成API说明文档【xml注释版】
⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...
ASP.NET Core WebApi使用Swagger生成API说明文档【特性版】
⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...
Asp.net Core WebApi 使用Swagger做帮助文档，并且自定义Swagger的UI
WebApi写好之后,在线帮助文档以及能够在线调试的工具是专业化的表现,而Swagger毫无疑问是做Docs的最佳工具,自动生成每个Controller的接口说明,自动将参数解析成json,并且能够在 ...
Asp.Net Core下使用swagger生成api文档
目录一.前期准备二.配置Swagger 三.参考 .Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag.两者的配置大同小异.这里以NSwag为例. 一.前期准备 ...

随机推荐

bootstrap字体图标在谷歌显示正常，在火狐显示异常的问题
bootstrap字体图标的使用现在有很多的网站支持字体图标,我所知道的有bootstrap,fontawesome,iconmoon,等等,可能还有其他我并不知道 bootstrap只要你的文件夹 ...
PCL 库安装
参考资料: http://www.cnblogs.com/newpanderking/articles/4022322.html VS2010+PCL配置 PCL共有两种安装方式安全安装版,个人配置 ...
天嵌E8卡片电脑USBWIFI驱动linux移植
下载驱动:http://pan.baidu.com/s/1sjL0Axn The drivers can be downloaded from Ralink website, the present ...
JAVA学习Swing章节标签JLabel中图标的使用
package com.swing; import java.awt.Color; import java.awt.Component; import java.awt.Container; impo ...
Permutation Test 置换检验(转）
Permutation Test 置换检验显著性检验通常可以告诉我们一个观测值是否是有效的,例如检测两组样本均值差异的假设检验可以告诉我们这两组样本的均值是否相等(或者那个均值更大).我们在实验中经 ...
vim recording
大家是否有这种经验,“不知道为什么按出recording状态,按ESC貌似无法直接退掉”的情况,个人已经有过好几次了.与其出来烦人还不如了解它,昨天我就花了点时间学习recording.怎么说,还是有 ...
Oracle学习(十四)：管理用户安全性
--用户(user) SQL> --创建一个名为 grace password是password 的用户,新用户没有不论什么权限 SQL> create user grace identi ...
[Mysql] "Too many connections"
刚刚在项目中遇到mysql数据库连接不够的问题,查了一点资料,记录下.异常信息主要为:Data source rejected establishment of connection, message ...
如何在自己设计的页面中调用metamask-1
启发: https://github.com/MetaMask/metamask-extension/issues/714 https://github.com/MetaMask/metamask-e ...
poj 1904(强连通分量+输入输出外挂)
题目链接:http://poj.org/problem?id=1904 题意:有n个王子,每个王子都有k个喜欢的妹子,每个王子只能和喜欢的妹子结婚,大臣给出一个匹配表,每个王子都和一个妹子结婚,但是国 ...