Flask集成Swagger生成在线文档与接口调试完整指南

本文适合了解RESTful架构概念，并对Swagger或OpenAPI规范有一定认知的读者阅读。

1. 理解RESTful架构

REST（Representational State Transfer，表述性状态转移）是一种基于HTTP协议的软件架构风格。它利用标准的HTTP方法（如GET、PUT、POST、DELETE）将Web系统中的服务抽象为资源进行操作。

当一个系统满足特定约束条件（如客户端-服务器架构、无状态通信、分层系统结构以及统一接口）时，该架构被称为RESTful。可以将其理解为规范化程度更高的REST架构。

简而言之，RESTful的核心在于通过HTTP请求（GET或POST等）获取或操作资源。例如，系统A对外暴露一个查询用户信息的接口，系统B通过发送HTTP请求至系统A，从而获取所需的用户数据资源。

因此，要实现RESTful风格的服务，关键在于向外部暴露标准化的接口。

对于具备Java开发经验的开发者而言，这通常意味着编写Controller类来处理请求。

以下Java Controller示例展示了如何暴露一个接口：通过浏览器访问指定地址（默认采用GET请求方式），即可获取任务详情信息。

<IP:端口/域名>/task/info/{taskId}

@RestController
@RequestMapping("/task")
public class TaskController {
	@GetMapping("/info/{taskId}")
	public R<TaskRes> getmTaskInfoById(@PathVariable String taskId) {
		TaskRes task = taskService.getTaskInfoById(taskId);
		return R.ok(task);
	}
}

2. Swagger/OpenAPI的核心价值

在Swagger出现之前，开发者主要依赖Word或Excel等工具编写接口文档，但这种方式存在明显缺陷。

主要弊端在于：当接口代码发生变更时，若未及时同步更新文档，会导致实际接口与文档描述不一致，从而使文档失去参考价值，甚至误导开发。

例如，原接口使用GET请求且通过URL参数传递taskId，若后续维护人员将其改为POST请求并将taskId移至请求体（JSON格式），却忘记更新文档，就会导致文档与实际接口脱节。

在Java生态中，可以通过在代码中使用自定义注解来自动生成接口文档，这在前后端分离项目中至关重要。其优势在于：开发阶段即可定义好接口文档，便于后续维护，确保文档与代码的一致性。

例如，在Java中可使用@API、@ApiModelProperty等注解对代码进行修饰，从而生成文档。

在Python中，实现类似功能的方式称为“装饰器”。

配置完成后，访问Swagger界面即可看到在线文档。该文档内容与Java代码中的注解描述信息保持一致。

尽管Java生态成熟，原生Swagger界面可能不符合现代使用习惯，因此常配合特定的UI插件使用。

OpenAPI3 (Swagger3) 访问地址：http://127.0.0.1:9090/swagger-ui/index.html

Knife4j UI 访问地址：http://127.0.0.1:9090/doc.html

在文档界面点击“调试”按钮，即可在线测试接口功能，这相当于将Postman等接口测试工具的功能集成到了文档系统中。

3. Python中实现Swagger的方案

在Flask框架中，通常使用flasgger库来集成Swagger。flasgger是Flask支持的Swagger UI组件，旨在方便调试基于Flask框架搭建的Web API接口。

安装flasgger库

pip install flasgger

flasgger的GitHub开源项目地址

https://github.com/flasgger/flasgger

flasgger的Gitee开源镜像地址

https://gitee.com/Flasgger/flasgger

4. flasgger实战案例

假设我们需要对外提供一个接口，其请求参数为复杂的JSON格式，包含字符串（userName）、对象（userInfo）、数字（age）和数组（hobby）。这种参数结构覆盖了99%以上的常见接口需求。

访问地址

http://127.0.0.1:8085/apidocs/

集成完成后，访问上述地址即可打开Python版本的Swagger文档页面。

页面可查看Models部分，其中描述了各个参数的结构。点击具体方法可查看调用示例，并可通过界面中的“Try it out”按钮进行请求调试。

进入调试页面后，修改参数值，点击“Execute”按钮执行请求。

下方将显示此次调用接口返回的响应信息。

与Java版本相比，界面风格基本一致。由于Java生态完善，支持Bootstrap UI或Knife4j UI等更多样化的展示风格，而目前Python生态中尚未找到对Bootstrap和Knife4j UI的直接支持。

如果您有Python版本的Bootstrap UI或Knife4j UI，或有类似的UI解决方案，欢迎联系交流，共同学习进步。

5. 完整代码示例

app.py

from flask import Flask, jsonify, request
from flasgger import Swagger, swag_from
server = Flask(__name__)
Swagger(server)
server.config['JSON_AS_ASCII']=False
@server.route('/flask/flasgger/demo',methods=['POST'])
@swag_from('demo.yml')
def demo_request():
    json_data = request.json
    result = {"code":"200","msg":"SUCCES","data":{"name":"xxxxxx","age":25,"job":"python"}}
    return jsonify(result)
if __name__ == "__main__":
    server.run(port=8085,debug=True)

demo.yml

tags:
  - falsk集成swagger示例
description:
    示例flasgger进行在线文档生成，添加用户信息，请求参数覆盖了常用的字符串、对象、数组、数字
parameters:
  - name: body
    in: body
    required: true
    schema:
      id: 接口参数示例
      properties:
        userName:
          type: string
          description: 用户自己的姓名
        userInfo:
            properties:
              hobby:
                type: array
                items:
                  type: string
                description: 用户的爱好
              age:
                type: integer
                description: 用户年龄
responses:
  200:
     description: 添加用户成功
     example:
  500:
     description: 添加用户失败
     example:

至此案例结束。本示例足以应对大部分常规使用需求。根据个人习惯，也可采用其他实现方式，具体细节请参考开源项目的使用说明。

flasgger的GitHub开源项目地址

https://github.com/flasgger/flasgger

flasgger的Gitee开源镜像地址

https://gitee.com/Flasgger/flasgger

本文介绍了Flask实现Swagger在线文档与接口测试的完整流程，更多Flask相关Swagger内容可搜索本站历史文章或继续浏览后续文章，感谢支持。