Flask项目集成Swagger文档的完整指南

洛溪

发布时间：2026-10-14| 4人浏览过

原创

本文详细介绍在Flask框架中集成Swagger文档的方法。通过安装flask-restplus库，开发者可以自动生成在线接口文档，解决传统文档维护繁琐的问题。文章包含具体的安装命令、代码示例及启动步骤，帮助开发者实现接口文档的实时更新与便捷查看。

Flask集成Swagger的优势与原理

本文主要讲解如何在Flask框架中集成Swagger文档。以往向同事提供接口文档时，通常采用编写独立文档的方式，一旦接口频繁修改，文档更新便显得极为繁琐。Swagger文档的出现解决了这一痛点，它提供了一套在线接口文档查看方案。当接口代码发生变动时，只需修改对应代码，文档即可自动同步更新，无需手动维护文档内容。具体效果可参考相关图示。

安装与配置步骤

本次集成方案参考flask-restplus官方文档。flask-restplus是flask-restful框架的增强版本，其功能定位类似于Django框架中的REST framework。在应用之前，需先安装该框架，执行以下命令：


pip install flask-restplus

代码示例与接口定义

接下来，结合官网示例编写一个简单的测试用例，以便直观感受其用法：


from flask import Flask
from flask_restplus import Api, Resource, fields, reqparse

app = Flask(__name__)
api = Api(app, version='1.0', title='TodoMVC API', description='A simple TodoMVC API',)

ns = api.namespace('todo', description='TODO operations')               # 模块命名空间

todo = api.model('Todo', {                               # 返回值模型
  'id': fields.Integer(readonly=True, description='The task unique identifier'),
  'task': fields.String(required=True, description='The task details')
})

parser = reqparse.RequestParser()                      # 参数模型
parser.add_argument('id', type=str, required=True, help="id")
parser.add_argument('name', type=str, required=True, help="名称")
parser.add_argument('volume', type=int, required=True, help="方量")


class TodoDAO(Resource):
  def __init__(self, *args, **kwargs):
    super().__init__(*args, **kwargs)
    self.params = parser.parse_args()

  @ns.expect(parser)                  # 用于解析对应文档参数，             
  @ns.response(200, "success response", todo)      # 对应解析文档返回值
  def get(self):
    return self.params


ns.add_resource(TodoDAO, "/to", endpoint="to_do")

app.run()