Flask Swagger 文档自动生成

 

        目前前后端交互的主流方式就是前后端分离，在某些简单的场合下后端渲染页面比较方便，但规模大一点的项目还是前端架构比较有优势，不管是框架支持，库支持，社区支持还是性能，开发效率而言，此时前后端的沟通方式变得跟移动端一样，后端提供一份API文档，API可以遵循Restful风格提供。

       独自全栈开发时往往没有API沟通的问题，如果前后端是两个人写，但后端需要维护一份API文档提供给前端，这是文档的编写仅仅是一个工作量的问题，另外需要注意的是修改了接口需要及时更新文档，我们这个时候一般都是以word文档的形式提供API文档。

       当队伍继续扩充时，后端需要多个共同维护一个API文档，这时就比较的麻烦，因为word文档并不能支持版本管理，所以需要以简单文本格式的写文档，以支持git进行版本管理，另外编写一般都是从最后开始加，容易有各种冲突，所以我们开始找一个能自动生成API文档以拜托手动编写和共同维护的问题。

       我们经过了解，API文档方面 Swagger 的功能最强大，并且页面也比较美观，我们也了解了 Flask-Docs 这种自动生成的库，但是页面美观及功能都不及Swagger。

       后来了解了 flask-restplus 这个库，github地址 https://github.com/noirbizarre/flask-restplus ，但是我们实际在使用的时候发现，这个库虽然功能强大，但是他对于API的编写是基于类的，而我们的项目目前都是基于函数的，所以接入需要给我们带来很大的开发量，所以我们后来根据 Flask-Docs 注释收集文档信息 跟 Swagger 语法 的特点自己实现。

       我们的思路基本是，我们注册路由的蓝图是根据网上资料实现的

class ApiBlueprint(object):

    def __init__(self, name):
        self.name = name

    def route(self, rule, **options):
        pass

    def register(self, bp, url_prefix=None):
        pass

        为每个 view会创建一个 ApiBlueprint 的对象，然后在初始化app的时候会把所有的 ApiBlueprint 的对象都注册进flask的路由中

from flask import Blueprint


def init_app_br(app):
    from app.api.views import view_demo

    api = Blueprint('api', __name__)
    view_demo.api.register(api)

    app.register_blueprint(api, url_prefix='/api')

         因为我们本身就都已经调用了这个 ApiBlueprint 的 route 方法来通过装饰器收集路由信息，我们就对这个方法进行了拓展，通过关键字参数收集文档需要的参数声明，错误声明，API数据模型声明及接口描述之类的其他数据，然后通过懒加载在第一次获取文档的json数据的时候，将收集数据按Swagger Json 语法生成 json数据，项目提供一个固定的 /api 路由指向 Swagger 文档查看器，默认查看我们自己编写的json数据接口地址。

         文档访问效果如下：

         生成效果达到预期，通过参数收集相比较 flask-restplus 不够足够优雅，但相比较于注释收集则不需要记忆太多的语法，并且这种做法对于我们目前的项目，改动非常小，基本都是添加文档的工作量。

         demo 项目的源码可以参考：https://github.com/yuxiaojie/api_demo ，如果自己项目也有改动量大的问题，可以根据自己需求实现收集的装饰器或者注册器，而解析成 Swagger Json 的语法是通用的，另外 Swagger 会提示语法有问题主要是因为，我使用了 非 http 的状态码用来表示我们自己自定义的错误码。