如何在Swagger UI中用默认错误Schema正确记录Flask abort方法错误

1. 先搞定默认错误Schema的配置 #

Flask-RESTX自带默认错误响应结构，你可以先显式定义（或确认API已自动注册）统一的错误Schema，避免后续引用混乱：

from flask_restx import Api, fields

api = Api()
# 定义全局通用的错误Schema
error_schema = api.model('Error', {
    'message': fields.String(description='错误描述'),
    'error': fields.String(description='错误类型', nullable=True),
    'status_code': fields.Integer(description='HTTP状态码')
})

2. 在alt_response中直接关联Schema #

用@blp.alt_response()时，指定schema参数为上面定义的错误Schema，Swagger UI就能自动生成对应的示例错误：

@blp.route('/protected')
class ProtectedResource(Resource):
    @blp.alt_response(401, schema=error_schema, description='未授权访问')
    def get(self):
        abort(401, message='Your entry is not authorized')

3. 全局配置更省心（不用每个接口手动加） #

如果不想逐个接口写alt_response，可以搞全局错误处理，自动把abort的错误映射到文档：

第一步：注册全局异常处理函数 #

from flask import jsonify
from werkzeug.exceptions import HTTPException

@api.errorhandler(HTTPException)
def handle_http_exception(e):
    response = e.get_response()
    response.data = jsonify({
        'message': e.description,
        'error': e.name,
        'status_code': e.code
    }).data
    response.content_type = 'application/json'
    return response

第二步：给API全局绑定常见错误响应 #

创建API实例时，直接批量声明常见错误码对应的Schema：

api = Api()
# 为所有接口统一添加401、403、404这类通用错误的文档
for code in [401, 403, 404]:
    api.response(code, schema=error_schema)

4. 别踩abort传Schema的坑 #

你之前尝试在abort()里传Api.Error_Schema完全没必要——abort()只负责返回错误数据，文档的Schema关联应该通过alt_response或全局配置来做，这样才能保证Swagger里的Schema引用和默认错误一致。

5. 自定义错误Schema的正确用法 #

如果需要定制错误结构，先定义统一的CustomErrorSchema，然后在所有需要的地方复用：

custom_error_schema = api.model('CustomError', {
    'error_msg': fields.String(required=True, description='详细错误信息'),
    'status': fields.Integer(required=True, description='状态码'),
    'request_id': fields.String(description='请求ID用于排查')
})

# 接口中直接关联自定义Schema
@blp.alt_response(401, schema=custom_error_schema)
def get(self):
    abort(401, error_msg='Your entry is not authorized', status=401, request_id='abc123')

按上面的步骤配置后，Swagger UI会正确显示错误响应的Schema和示例数据，同时保证所有接口的错误格式统一。

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