使用OpenAPI 3.0.2时Flasgger的Schema定义无法在Swagger-UI中显示的问题咨询

嗨，我来帮你分析下这个问题~

这其实不是你的定义方式被弃用了，而是OpenAPI 3.x和2.x在响应结构的定义语法上有本质区别，你现在用的是OpenAPI 2.x的写法，放到3.0.2版本自然无法被正确识别，所以Swagger-UI才没显示Schema。

具体来说：

• 在OpenAPI 2.x中，我们用schema字段直接定义响应结构；
• 但到了OpenAPI 3.x，这个逻辑被调整了，需要用content字段包裹，同时指定响应的媒体类型（比如application/json），再在媒体类型下定义schema。

给你两个适配OpenAPI 3.0.2的修改方案：

方案1：直接修改响应结构定义 #

def process_document():
    """
    Process document
    ---
    responses:
        500:
            description: Fatal Error Occurred
        200:
            description: Job submitted successfully
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            job_id:
                                type: string
                                description: Job ID
    """
    job_id = uuid.uuid4()
    return jsonify({
        "job_id": job_id,
    })

方案2：复用Schema定义（替代原来的definitions） #

如果想复用JobSubmissionResponse这个定义，OpenAPI 3.x用components/schemas替代了2.x的definitions，写法如下：

def process_document():
    """
    Process document
    ---
    components:
        schemas:
            JobSubmissionResponse:
                type: object
                properties:
                    job_id:
                        type: string
                        description: Job ID
    responses:
        500:
            description: Fatal Error Occurred
        200:
            description: Job submitted successfully
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/JobSubmissionResponse'
    """
    job_id = uuid.uuid4()
    return jsonify({
        "job_id": job_id,
    })

修改后重启服务，Swagger-UI应该就能正常显示返回的Schema结构了。Flasgger完全支持OpenAPI 3.x规范，只是要跟着版本调整写法哦~

备注：内容来源于stack exchange，提问作者alessandro ferrucci