Flask Swagger 文档自动生成_flask blueprint swagger-优快云博客

本文介绍了在前后端分离的项目中，如何利用Flask和Swagger解决API文档的编写和维护问题。随着团队扩大，手动维护word文档变得困难，于是转向寻找能够自动生成API文档的解决方案。作者对比了Flask-Docs和flask-restplus，最终选择基于现有项目结构，利用Flask的蓝图功能和Swagger的JSON规范，实现了自定义的API文档生成器。通过装饰器收集路由信息，生成Swagger JSON数据，并提供固定路由展示文档。项目源码已开源，适用于不希望大规模重构代码的团队。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

目前前后端交互的主流方式就是前后端分离，在某些简单的场合下后端渲染页面比较方便，但规模大一点的项目还是前端架构比较有优势，不管是框架支持，库支持，社区支持还是性能，开发效率而言，此时前后端的沟通方式变得跟移动端一样，后端提供一份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 语法的特点自己实现。