简介

随着微软.NET Core的诞生,除了恐龙以外第二个应该灭绝的.NET程序员,总算看到了一米阳光。真是做噩梦都没想到,有一天我们也可以抛弃Windows这2货,去拥抱主流的Linux+Docker的时代。

尝试一些事,遭遇失败后从中学习,比什么事都不做更好。—马克.佐克伯

Swagger对我们有什么帮助?

对于开发人员来说,调试API接口和生成API文档是一件极其头疼的事情。我们在百忙之中,不得不为前端开发人员编写接口文档,来描述系统中N个接口的参数及返回状态,再借助PostMan等第三方工具来测试API的正确性。

在有了Swagger后,这项体力活终于得到了极大的改善,我们不但可以自动构建漂亮的交互式API说明文档,还可以直接调试API接口的正确性。最新版的Swagger已经完美支持Open Api规范及JWT Token授权访问等。

我们可以用它来做什么?

  • 生成精美的API接口文档
  • 调试JWT授权接口
  • 生成各个类库中视图模型的描述

项目开源地址

Swagger项目开源地址:https://github.com/domaindrivendev/Swashbuckle.AspNetCore

1.创建一个.NET Core项目

首先,新建一个.NET Core 3.x Web Api 项目,打开Nuget安装管理器,勾选左下角的显示预览发行包,搜索Swashbuckle.AspNetCore,版本选择5.0.0-rc4的点添加,注意因为.NET Core 3.x刚出不久,目前支持的库很多都是预览版,这里我选5.0.0-beta是会报错,选5.0.0-rc4使用正常。

设置生成XML描述信息

耐心等待几秒钟添加完成后,我们选中左侧刚才创建的Api项目,右键>属性(Mac里叫选项),勾选生成XML文档,这个是用来生成为Swagger所用的描述信息。

开始配置Swagger

然后我们打开Startup.cs文件,来对Swagger配置进行一些必要的配置,在ConfigureServices方法我们添加一下配置:

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Crypto Exchange",
Description = "基于.NET Core 3.0 的区块链数字货币交易所",
Contact = new OpenApiContact
{
Name = "Microfisher",
Email = "276679490@qq.com",
Url = new Uri("http://cnblogs.com/microfisher"),
},
}); // 加载程序集的xml描述文档
var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
var xmlFile = System.AppDomain.CurrentDomain.FriendlyName+ ".xml";
var xmlPath = Path.Combine(baseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
})

参数都很简单,就是Swagger界面上显示的一些信息,注意这里一定要习惯使用Path.Combine来拼接路径,很多同学喜欢双斜杠来拼接,在Mac或Linux下是会出问题的。既然已经拥抱开源技术,尽量使用Mac或Linux来开发.NET Core吧。然后我们在Configure方法里添加以下代码:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Crypto Exchange");
// 访问Swagger的路由后缀
c.RoutePrefix = "swagger";
});

预览一下小成果

到这里为止,最基本的配置就完成了,其中RoutePrefix是访问Swagger的路由,如果设置为空则不需要输入/swagger后缀来访问。现在我们F5启动项目看看,我的本地网址是https://localhost:5000,所以直接访问:https://localhost:5000/swagger如下图所示,我去这界面也太丑了,说好的精美绝伦呢?不急不急,我们慢慢调优

启用JWT授权

目前很多网站都使用了JWT(JSON WEB TOKEN)来作为账户系统的认证授权,JWT以它的简单、高效、分布式优势很快成为各大网站及APP的流行验证方式。这里我们不做过多的介绍,如果大家感兴趣我可以再写一篇长文来介绍的优势和使用方法。我们继续来为Swagger添加JWT授权认证,依旧打开Startup.cs文件,修改上面ConfigureServices方法中的代码:

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Crypto Exchange",
Description = "基于.NET Core 3.0 的区块链数字货币交易所",
Contact = new OpenApiContact
{
Name = "Microfisher",
Email = "276679490@qq.com",
Url = new Uri("http://cnblogs.com/microfisher"),
},
}); c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
{
Description = "在下框中输入请求头中需要添加Jwt授权Token:Bearer Token",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
BearerFormat = "JWT",
Scheme = "Bearer"
}); c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference {
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] { }
}
}); var baseDirectory = System.AppDomain.CurrentDomain.BaseDirectory;
var xmlFile = System.AppDomain.CurrentDomain.FriendlyName + ".xml";
var xmlPath = Path.Combine(baseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});

预览一下授权设置

然后再启动项目,你会发现右侧多了一个Authorize绿色的带锁按钮,这个按钮点开后就可以设置我们的JWT Token信息了,格式是:Bearer Token,注意Bearer于Token之间有个空格。设置好Token后,你请求任意的API接口时,Swagger会自动附带Token到请求的Header中。

创建一个RESTFUL接口

上面我们已经实现了Swagger的各项配置,现在我们来删除默认生成的控制器WeatherForecastController及视图模型WeatherForecast,新建一个AccountController及几个视图模型,让Swagger返回带描述的接口文档。

//[Authorize]
[Produces("application/json")]
[Route("v1/[controller]")]
[ApiController]
public class AccountController : ControllerBase
{
/// <summary>
/// 创建信息
/// </summary>
/// <param name="createViewModel">参数</param>
/// <returns>状态</returns>
[HttpPost]
public StatusViewModel Post([FromBody]CreateViewModel createViewModel)
{
return new StatusViewModel { };
} /// <summary>
/// 删除信息
/// </summary>
/// <param name="deleteViewModel">参数</param>
/// <returns></returns>
[HttpDelete]
public StatusViewModel Delete([FromQuery]DeleteViewModel deleteViewModel)
{
return new StatusViewModel { };
} /// <summary>
/// 查询信息
/// </summary>
/// <param name="queryViewModel">参数</param>
/// <returns></returns>
[HttpGet]
public StatusViewModel Get([FromQuery]QueryViewModel queryViewModel)
{
return new StatusViewModel { };
} /// <summary>
/// 修改信息
/// </summary>
/// <param name="updateViewModel">参数</param>
/// <returns></returns>
[HttpPut]
public StatusViewModel Put([FromQuery]UpdateViewModel updateViewModel)
{
return new StatusViewModel { };
}
}

创建几个视图模型

再按自己喜欢的风格新建几个视图模型,用///为各个字段添加summary后如下:

public class UpdateViewModel
{
/// <summary>
/// ID
/// </summary>
public long Id { get; set; } /// <summary>
/// 账号
/// </summary>
public long Account { get; set; } /// <summary>
/// 密码
/// </summary>
public long Password { get; set; }
}

测试最终成果

最后我们来看看效果,随便展开一个API接口,可以看到我们给视图模型写的注释已经显示在Swagger上了,前端开发人员一看就懂,输入一些接口参数,点一下执行就能看到返回值了:

再看我们的请求Header中已经包含了JWT授权信息(Bearer 123456789)是我随意设置的,让你们前端调试的时候换成你们的Token就行了。

如何使用Swagger为.NET Core 3.0应用添加JWT授权说明文档的更多相关文章

  1. .NET Core 2.0 Preview 1发布下载和文档

    .NET Core 2.0.0 Preview 1 发布于 2017 5.10. 你可以通过 Visual Studio 2017 Preview 15.3, Visual Studio for Ma ...

  2. swagger api文档添加jwt授权配置

    最近写的swagger文档,要加jwt授权,所以几经google终于搞定了,简简单单几行配置如下: securityDefinitions: APIKey: type: apiKey name: Au ...

  3. .NET Core 3.0 使用Nswag生成Api文档和客户端代码

    摘要 在前后端分离.Restful API盛行的年代,完美的接口文档,成了交流的纽带.在项目中引入Swagger (也称为OpenAPI),是种不错的选择,它可以让接口数据可视化.下文将会演示 利用N ...

  4. asp.net core 2.0的认证和授权

    在asp.net core中,微软提供了基于认证(Authentication)和授权(Authorization)的方式,来实现权限管理的,本篇博文,介绍基于固定角色的权限管理和自定义角色权限管理, ...

  5. 【转载】asp.net core 2.0的认证和授权

    在asp.net core中,微软提供了基于认证(Authentication)和授权(Authorization)的方式,来实现权限管理的,本篇博文,介绍基于固定角色的权限管理和自定义角色权限管理, ...

  6. 把旧系统迁移到.Net Core 2.0 日记 (18) --JWT 认证(Json Web Token)

    我们最常用的认证系统是Cookie认证,通常用一般需要人工登录的系统,用户访问授权范围的url时,会自动Redirect到Account/Login,登录后把认证结果存在cookie里. 系统只要找到 ...

  7. .net core 2.0的认证和授权

    在asp.net core中,微软提供了基于认证(Authentication)和授权(Authorization)的方式,来实现权限管理的,本篇博文,介绍基于固定角色的权限管理和自定义角色权限管理, ...

  8. ASP.Net Core 3.0 中使用JWT认证

    JWT认证简单介绍     关于Jwt的介绍网上很多,此处不在赘述,我们主要看看jwt的结构.     JWT主要由三部分组成,如下: HEADER.PAYLOAD.SIGNATURE HEADER包 ...

  9. Blazor client-side + webapi (.net core 3.1) 添加jwt验证流程(非host)第二步 添加Identity

    添加Identity数据上下文 安装nuget包:Microsoft.AspNetCore.Identity.EntityFrameworkCore 创建ApplicationDbContext类 创 ...

随机推荐

  1. 2019年9月3日安卓凯立德全分辨率(路况)夏季版C3551-C7M24-3K21J25懒人包

    拷贝懒人包NaviOne文件夹到机器根目录或内存卡根目录下:安装其中的apk程序 2019凯立德C3551-C7M24-3K21J25新组合懒人包 [分辨率]:自适应 [适用系统]:Android2. ...

  2. [Pandas] 01 - A guy based on NumPy

    主要搞明白NumPy“为什么快”. 学习资源 Panda 中文 易百教程 远程登录Jupyter笔记本 效率进化 四步效率优化 NumPy 底层进行了不错的优化. %timeit 对于任意语句,它会自 ...

  3. Qt 做一个类似微信滑动聊天界面的demo

    版权声明:本文为博主原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接和本声明. 本文链接:https://www.cnblogs.com/lihuidashen/p/115889 ...

  4. 基于操作系统原理的Linux 系统的安装

    一.实验目的 1.了解Linux操作系统的发行版本. 2.掌握Red Hat Linux 9.0的安装方法. (可用Red Hat Linux 5.0版本替代9.0版本) 3.了解Linux其他版本( ...

  5. pycharm使用sublime/boxy配色方案

    # 展示效果图 1. github官网连接:https://github.com/simoncos/pycharm-monokai 2.克隆代码并解压文件 3.PyCharm -> File - ...

  6. CentOS 8 都发布了,你还不会用 nftables?

    原文链接:CentOS 8 都发布了,你还不会用 nftables? 如果你没有生活在上个世纪,并且是云计算或相关领域的一名搬砖者,那你应该听说最近 CentOS 8 官方正式版已经发布了,CentO ...

  7. ajax跨域问题以及解决方案

    转:https://blog.csdn.net/csdn_ds/article/category/6937392/3 在工作中,大家应该都遇到过ajax跨域问题,浏览器的错误如下: XMLHttpRe ...

  8. Hibernate教程 ---简单易懂

    1 web内容回顾 (1)javaee三层结构 (2)mvc思想 2 hibernate概述 3 hibernate入门案例 4 hibernate配置文件 5 hibernate的api使用 Hib ...

  9. gitbook 入门教程之从零到壹发布自己的插件

    什么是插件 Gitbook 插件是扩展 Gitbook 功能的最佳方式,如果 Gitbook 没有想要的功能或者说网络上也没有现成的解决方案时,那么只剩下自食其力这条道路,让我们一起来自力更生开发插件 ...

  10. docker 使用及基本命令

    一.docker简单使用 a.列出镜像 docker images b.从docker hub拉取最新版本镜像 docker pull xxx 错误: Error response from daem ...