简介

本教程采用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使用正常。

设置生成xml描述信息

耐心等待几秒钟添加完成后，我们选中左侧刚才创建的api项目，右键>属性（mac里叫选项），勾选生成xml文档，这个是用来生成为swagger所用的描述信息。

开始配置swagger

然后我们打开startup.cs文件，来对swagger配置进行一些必要的配置，在configureservices方法我们添加一下swagger配置：

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";
});

预览一下小成果

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

启用api文档的jwt授权

目前很多网站都使用了jwt（json web token）来作为账户系统的认证授权，jwt以它的简单、高效、分布式优势很快成为了网站的流行验证方式。这里我们不做过多的介绍，如果大家感兴趣我可以再写一篇长文来介绍jwt的优势和使用方法。我们继续来为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就行了。

项目代码，喜欢请加个星

https://github.com/microfisher/tutorials

黄山市民网：https://www.huangshanshimin.com/

简介