how to display query parameters in swagger documentation

[yjk891]

I am wondering if it is available to display query parameter in swagger documentation.

Here is what I implemented on my project. To obtain query parameters, ReqParser - specifically add_argument method - is used but there is no parameters for description.

I thought described query params are available, because swagger supports this.

If there is any other solutions, hope to let me know.

[VukW]

Hi! Though documentation keeps silence about query params, I've found a solution:

@api.route('/api/rec/<string:uid>')
@api.doc(params={'uid': {'description': 'user UID'},
                 'param1': {'description': 'blabla', 'in': 'query', 'type': 'int'}})
class MyResource(Resource):
    @api.doc(params={'param2': {'description': 'another param just for that get route',
                                'type': 'int', 'default': 1}})
    def get(self, uid):
        param2 = int(request.args.get('param2'))
        param1 = int(request.args.get('param1'))
        return {'uid': uid, 'params': param1 + param2}

    def post(self, uid):
        param1 = request.args.get('param1')
        return {'uid': uid, 'params': param1}

It creates two endpoints: GET /api/rec/123321?param1=1&param2=3 and PUT /api/rec/123321?param1=100500

What is here:

1. You may add additional non-path arguments to api.doc. Though you can explicitly define them as 'in: 'query', it is not necessary; all params not in path are used as query params by default.
2. You may add additional doc & params to separate method (like param2 for GET). They are also considered as query params.
3. By default, all non-path params have 'required': False

[j5awry]

Please open tickets against the following as this project is no longer maintained:

https://github.com/python-restx/flask-restx

Some of the big todo items include better documentation, and removing the reqparser as it currently exists (that's been slated for a long time, but the former head maintainer never let us know the plans)

[Holmes5]

I was struggling with this same problem all afternoon today, and in the documentation, I found that you can pass a parser object (from reqparse) to @api.expect. A minimal working example is below:

import flask
from flask_restplus import Resource, Api, reqparse, inputs


app = flask.Flask(__name__)
api = Api(app)


parser = reqparse.RequestParser()
parser.add_argument('random_flag', type=inputs.boolean,
                    help="You know what it's for.",
                    default=True, required=True)


def do_stuff(random_flag=True):
    return ('cat' if random_flag else 'dog')


@api.route('/foo')
class Bar(Resource):
    @api.expect(parser)
    def get(self):
        args = parser.parse_args()
        return do_stuff(**args)

[Fhernd]

I was struggling with this same problem all afternoon today, and in the documentation, I found that you can pass a parser object (from reqparse) to @api.expect. A minimal working example is below:

import flask
from flask_restplus import Resource, Api, reqparse, inputs


app = flask.Flask(__name__)
api = Api(app)


parser = reqparse.RequestParser()
parser.add_argument('random_flag', type=inputs.boolean,
                    help="You know what it's for.",
                    default=True, required=True)


def do_stuff(random_flag=True):
    return ('cat' if random_flag else 'dog')


@api.route('/foo')
class Bar(Resource):
    @api.expect(parser)
    def get(self):
        args = parser.parse_args()
        return do_stuff(**args)

My own example:

# ...

parser = reqparse.RequestParser()
parser.add_argument('clientId', type=int, help='Client ID', required=True)
parser.add_argument('year', type=int, help='Month registry year', required=True)
parser.add_argument('month', type=int, help='Month registry month', required=True)


@api.route('/exists')
class MonthlyReporteExists(Resource):
    @api.doc('Checks if a monthly report exists')
    @api.expect(parser)
    def get(self):
        client_id = request.args.get('clientId')
        year = request.args.get('year')
        month = request.args.get('month')
        return get_monthly_report_exists(client_id, year, month)

# ...