如何使用Swagger为.NET Core 3.0应用添加JWT授权说明文档

简介

本教程采用WHY-WHAT-HOW黄金圈思维模式编写，黄金圈法则强调的是从WHY为什么学，到WHAT学到什么，再到HOW如何学。从模糊到清晰的学习模式。大家的时间都很宝贵，我们做事前先想清楚为什么要做，学完能达到什么样的目标，然后我们再考虑要达到这个目的，通过什么样的方法来实现。

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

为什么要学？

对于开发人员来说，**调试API接口和生成API文档是一件极其头疼的事情。我们在百忙之中，还不得不为前端开发人员编写接口文档，来描述系统中N个接口的参数及返回状态，再借助PostMan等第三方工具来测试API的正确性。在Swagger诞生后，这项体力活终于得到了极大的改善，我们不但可以自动构建漂亮的交互式API说明文档，还可以直接调试API接口的正确性。最新版的Swagger已经完美支持Open Api规范及JWT Token授权访问等。

能学到什么？

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

怎么做？

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

创建一个.NET Core项目

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