Swagger 导出API

Swagger 导出API

这算是在博客园的第一篇博客吧，之后发的应该也会同步到博客园上。

此前的博客地址: https://blog.mytyiluo.cn

Swagger简介

Swagger是一个开源软件框架，可帮助开发人员设计，构建，记录和使用RESTful Web服务。

其中，Swagger可以生成一个交互式的API控制台，以便于快速测试API。

从个人角度讲，Swagger对于前后端分离的小团队来说是非常有帮助的。尤其是像我们这种平时没写文档习惯的人来说，Swagger能根据代码自动生成文档可谓是一大福音，再也不用被人追着问这API到底是怎么用的。

这里，我将会具体说下最近我使用Swagger的一些心得和体会，团队的开发环境如下：

• ASP.NET Core 2.1 (Visual Studio 2017 Community)
• 微信小程序 (官方工具+Visual Studio Code)

生成Swagger API 文档

对于ASP.NET Core来说，生成文档这一步还是相对容易的，且对代码基本没有侵入性。只需在Startup中配置一下即可，大致步骤基本如下：

添加NuGet包

这里，我所使用的是Swashbuckle.AspNetCore，直接用VS的NuGet包管理器下载即可。

然后在ConfigureServices中配置如下:

services.AddSwaggerGen(c =>
{
    // 定义文档
    c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" });
});

并在Configure中启用该Services：

// 使用Swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Qincai API v1");
});

随后运行，打开浏览器host/swagger即可看到所生成的API文档。

若还有不清楚的，可以参考微软官方的文档。

完成到这里，是不是发现你和图中生成的样子有点不太一样，比如说，为什么没有注释，以及认证用的小锁，那这里我们就需要进一步配置。

添加XML注释

如果大家有在VS中写C#经历的话，肯定会对XML注释影响深刻，通过简单的///就可以自动生成规范的注释格式。那这里，我们的Swagger也正是利用了这些XML注释来标记对应的API。

首先，我们需要启用VS中导出XML文档的功能，在项目属性中，生成 > 输出，勾选XML文档文件，并填写对应的路径，我所写的是项目根目录。

然后再到之前的ConfigureServices中添加如下：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" });

    // file 是你在项目属性中配置的相对路径
    var filePath = System.IO.Path.Combine(AppContext.BaseDirectory, file);
    c.IncludeXmlComments(filePath);
});

重新生成，再运行，你可以看到Swagger中就对API以及参数添加上了注释。

添加认证功能

在实际开发中，我们常常是需要给我们的API添加上认证功能以避免非法的访问，因此我们也就需要给Swagger中的API标识上是否需要认证，并且添加提供Token的功能，以方便在Swagger的控制台中调试。

简单来说，还是在ConfigureServies中，配置如下：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Qincai API", Version = "v1" });

    var filePath = System.IO.Path.Combine(AppContext.BaseDirectory, file);
    c.IncludeXmlComments(filePath);

    // 定义认证方式
    c.AddSecurityDefinition("Bearer", new ApiKeyScheme
    {
        In = "header",
        Description = "请键入JWT Token，格式为'Bearer '+你的Token。",
        Name = "Authorization",
        Type = "apiKey"
    });

    // 网上为全局API添加认证参数的方法
    // c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>> {
    //     { "Bearer", Enumerable.Empty<string>() },
    // });

    // 在过滤器中为需要认证的API添加对应参数
    // 过滤器的定义见下文
    c.OperationFilter<AuthorizationHeaderOperationFilter>();
});

这里值得说一下的是，网上普遍都是全局添加认证参数，导致一些不需要认证的API也被打上了标识，这在Swagger 控制台中影响倒不大，但在后续的导出API时就麻烦了，所有在这里，我使用自定义过滤器的方式来只为需要认证的API添加认证参数。

根据上文，我们先定义一个AuthorizationHeaderOperationFilter类，它需要实现IOperationFilter接口，类定义如下：

/// <summary>
/// 判断是否需要添加Authorize Header
/// </summary>
public class AuthorizationHeaderOperationFilter : IOperationFilter
{
    /// <summary>
    /// 为需要认证的Operation添加认证参数
    /// </summary>
    /// <param name="operation">The Swashbuckle operation.</param>
    /// <param name="context">The Swashbuckle operation filter context.</param>
    public void Apply(Operation operation, OperationFilterContext context)
    {
        // 获取对应方法的过滤器描述
        // 应该也就是所添加的Attribute
        var filterPipeline = context.ApiDescription.ActionDescriptor.FilterDescriptors;
        // 判断是否添加了AuthorizeFilter
        // 也就是[Authorize]
        var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is AuthorizeFilter);
        // 判断是否添加了IAllowAnonymousFilter
        // 也就是[AllowAnonymous]
        var allowAnonymous = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is IAllowAnonymousFilter);

        // 仅当需要认证且不是AllowAnonymous的情况下，添加认证参数
        if (isAuthorized && !allowAnonymous)
        {
            // 若该Operation不存在认证参数的话，
            // 这个Security将是null，而不是空的List
            if (operation.Security == null)
                operation.Security = new List<IDictionary<string, IEnumerable<string>>>();

            // 添加认证参数
            operation.Security.Add(new Dictionary<string, IEnumerable<string>>
            {
                { "Bearer", new string[] { } }
            });
        }
    }
}

重新生成后运行，应该就可以看到需要认证的API都带上了一把小锁。

注意事项

虽说配置并不算难，但还是需要注意一些地方。

1. 注意写好XML注释

   之前也说了，Swagger的注释是根据XML文档生成的，反过来说，如果你没写XML注释，Swagger上也就是不会有注释的。

   另外，在你启用XML文档输出之后，VS也会很贴心的为你把没有写XML注释的地方都标为Warning。╮(╯▽╰)╭，所以安心的把注释都补一遍吧。

2. 为参数添加数据注解

   Swagger是支持部分数据注解的，比如[Required]之类的。

   结合[ApiController]自带的模型验证功能，岂不美哉。

3. 将XML文档复制到输出目录

   若你在发布应用后发现XML不见了，那可能就是你没有为XML文档文件配置复制到输出目录的属性。

   打开资源管理器，右键对应的文件，我们在属性中可以看到有复制到输出目录的属性，将其设置为始终复制就Ok。

   

以上就是我最近所用到的Swagger的一些功能。

导出微信小程序可用的API

在一开始也说了，使用Swagger的主要目的就是方便小团队的沟通，但事实上，因为我们前端的人少（大家都是CSS鬼才），导致我们开发新API的速度往往比前端进度快，没几天前端那边就需要更新一下API的库（将小程序的CallBack封装成Promise）。

因此，就有了根据Swagger自动生成Js可用的API文件的想法，其实想法的本身是来自于Abp项目的设计（真的很优秀），但出于一些方面的考虑，我们姑且还没采用Abp。

随后，就是查找资料了，确实Swagger有这方面的支持，其中官方关于Js的库是完全动态的，但可惜不适用于小程序。然后，就发现了第三方的swagger-js-codegen，可用于生成静态的Js代码，且提供了自定义模板的功能。网上也不少基于这个库的其他模板，比如说axios之类的，但没有适用于微信小程序的，不过问题不大，模板是基于mustache的，动手撸就是了。

模板代码有点长就不在这里放出了，大家还请移步GitHub。

这里我就简单说下大致思路，

模板本身是基于原来的nodejs模板改的，我们所需做的就是将http请求部分的代码改为使用wx.request，如下简单的封装即可:

/**
* HTTP Request
* @method
* @name {{&className}}#request
* @param {string} method - HTTP 请求方法
* @param {string} url - 开发者服务器接口地址
* @param {object} data - 请求的参数
* @param {object} headers - 设置请求的 header ,默认为 application/json
*/
request(method, url, parameters, data, headers){
    return new Promise((resolve, reject) => {
        wx.request({
            url: url,
            data: data,
            header: headers,
            method: method,
            success: res => {
                if(res.statusCode >= 200 && res.statusCode <= 299) {
                    resolve(res.data)
                } else {
                    reject(res)
                }
            },
            fail: e => reject(e)
        })
    })
}

对应method的话，基本没怎么改，只根据微信小程序所有参数都是传递给data，做了点简化。

对于认证部分，根据我们自己的需求，换成了这样的实现：

new Promise((resolve, reject) => {
    this.authenticate()
    .then(token => {
        headers['Authorization'] = 'Bearer ' + token;
        resolve(this.request('{{method}}', domain + path, parameters, data, headers))
    })
})

其中this.authenticate是由外部传入的function，返回一个包含Token的Promise。

导出后，在小程序中的使用就类似于:

import API from './api.js'

api = new API('http://localhost:5000')
api.setAuthenticate(function () {
    return new Promise((resolve, reject) => {
        // 你的认证逻辑
        resolve(token)
    })
})

然后，就可以开心地调用各种方法了。

最后，再放一遍Demo的链接：https://github.com/yiluomyt/swagger-wxopen-codegen-template，发现有问题欢迎提Issue。