Flask与Swagger UI故障排查及RESTful接口技术咨询

先来说说你遇到的两个问题，我一步步帮你梳理清楚：

1. 如何获取Flask所需的request.json？ #

首先你得先从Flask导入request对象，这是获取请求数据的核心。request.json会自动解析请求体里的JSON数据，但有个前提：客户端发送请求时必须设置请求头Content-Type: application/json，否则Flask无法识别JSON格式，request.json会返回None。

修正后的代码示例：

from flask import Flask, request  # 新增request的导入
from flask_swagger import Swagger
from flask_cors import CORS

def init_deserializer_restful_api():
    PORT = 8000
    app = Flask(__name__)
    Swagger(app)
    CORS(app)

    @app.route("/deserialize", methods=['POST','GET'])
    def handle_deserialization_request():
        if request.method == 'POST':
            # 获取JSON请求体数据
            request_data = request.json
            if not request_data:
                return {"error": "请发送JSON格式数据，并设置请求头Content-Type为application/json"}, 400
            # 这里编写你的反序列化业务逻辑
            return {"result": "反序列化成功", "received_data": request_data}, 200
        elif request.method == 'GET':
            # GET请求可以返回服务状态
            return {"status": "反序列化服务运行正常"}, 200

    app.run(port=PORT, host="0.0.0.0")

if __name__ == "__main__":
    init_deserializer_restful_api()

如果客户端没正确设置请求头，你可以尝试用request.get_json(force=True)强制解析JSON，但更推荐让客户端规范设置请求头，这是RESTful API的标准做法。

2. 如何让Swagger正常工作（解决404问题） #

你遇到的404问题有两个原因：路径拼写错误和Swagger UI访问路径不对，另外还要给接口添加Swagger能识别的注释才能生成文档：

问题1：端点访问404 #

你的路由是/deserialize，但你访问的是http://localhost:8000/deserializer（多了个字母r），这是典型的拼写错误，正确的访问路径应该是http://localhost:8000/deserialize。

问题2：Swagger UI无法访问 #

使用flask-swagger包时，Swagger UI的默认访问路径是/swagger，所以你需要访问http://localhost:8000/swagger才能看到接口文档，而不是直接访问业务端点。

问题3：接口缺少Swagger注释 #

要让Swagger生成接口文档，你需要给路由函数添加符合Swagger规范的文档字符串（用---分隔的YAML格式），示例如下：

@app.route("/deserialize", methods=['POST','GET'])
def handle_deserialization_request():
    """
    ---
    post:
      summary: 处理反序列化请求
      description: 接收JSON格式的序列化数据，执行反序列化操作后返回结果
      parameters:
        - in: body
          name: request_body
          required: true
          schema:
            type: object
            properties:
              serialized_data:
                type: string
                description: 需要被反序列化的字符串
      responses:
        200:
          description: 反序列化成功
          schema:
            type: object
            properties:
              status:
                type: string
              deserialized_result:
                type: object
        400:
          description: 请求格式错误
    get:
      summary: 检查服务状态
      description: 返回反序列化服务的运行状态
      responses:
        200:
          description: 服务正常运行
          schema:
            type: object
            properties:
              status:
                type: string
    """
    # 你的业务逻辑代码...

额外建议：用Flask-RESTX替代Flask-Swagger #

如果想更优雅地构建带Swagger文档的RESTful API，推荐使用flask-restx（原flask-restplus的维护分支），它提供了更强大的API文档生成能力，示例代码如下：

from flask import Flask
from flask_restx import Api, Resource, fields
from flask_cors import CORS

def init_deserializer_restful_api():
    PORT = 8000
    app = Flask(__name__)
    CORS(app)
    # 创建Api对象，自动生成Swagger文档
    api = Api(app, version='1.0', title='反序列化API', description='用于处理数据反序列化的RESTful API')

    # 创建命名空间
    ns = api.namespace('deserialize', description='反序列化操作')

    # 定义请求模型
    deserialize_model = api.model('DeserializeRequest', {
        'serialized_data': fields.String(required=True, description='需要反序列化的字符串')
    })

    # 定义响应模型
    success_response = api.model('SuccessResponse', {
        'status': fields.String(description='状态信息'),
        'deserialized_result': fields.Raw(description='反序列化后的结果')
    })

    @ns.route('/')
    class DeserializeResource(Resource):
        @ns.doc('get_status')
        def get(self):
            """获取服务运行状态"""
            return {'status': '服务正常运行'}

        @ns.doc('deserialize_data')
        @ns.expect(deserialize_model)
        @ns.marshal_with(success_response)
        def post(self):
            """处理反序列化请求"""
            request_data = api.payload
            # 替换为你的实际反序列化逻辑
            return {
                'status': '反序列化成功',
                'deserialized_result': request_data['serialized_data']
            }

    app.run(port=PORT, host="0.0.0.0")

if __name__ == "__main__":
    init_deserializer_restful_api()

使用flask-restx的话，Swagger UI默认访问路径还是/swagger，启动后访问就能看到完整的接口文档，包括请求参数、响应格式等，比flask-swagger更直观易用。

内容的提问来源于stack exchange，提问作者LoveMeow