FRAMEWORK » FLASK » EXTENSIONS

RESTX

Last updated:
Reference:flask-restx.readthedocs.io
Package:pypi

Decorators ​

Route definition ​

Endpoint with no arguments:

python
@api.route('/tasks')

Endpoint that requires an argument (available converters):

python
@api.route('/tasks/<string:name>')

Input args ​

python
@api.doc(
    description='Documentation of this API',
    params={  # For query parameters
        'id': {
            'description': 'An ID',
            'in': 'query',
            'type': 'int',
        },
        'format': {
            'description': 'A file format',
            'in': 'query',
            'type': 'string',
            'enum': ['json', 'csv'],
        }
    }
)
@api.expect(my_model)  # Expected input parameters (body)

Output data ​

python
@api.marshal_with(my_model)    # Expected return values, code, description
@api.response(200, 'Success')  # May be used several times
@api.header()                  # Response header

If the same endpoint returns multiple data formats:

  • Use marshal() when returning JSON data
  • Use Response() when returning anything else
python
from flask_restx import marshal

def get(self):
    output_format = request.args.get('format', 'json')
    output_type = request.args.get('type', 'summary')
    if output_format == 'csv':     # CSV data
        return Response(csv_content, mimetype='text/csv')
    if output_type == 'detailed':  # Dict using detailed_model
        return marshal(detailed_json_content, detailed_model), 200
    # Dict using summary_model
    return marshal(summary_json_content, summary_model), 200

Models ​

python
my_model = api.model('ResourceName', {
    'id': fields.Integer,
    'name': fields.String,
})