expects vs params

[leberknecht]

Ask a question
When i have something like this:

@my_api.expect(input_model)

with the model being:

input_model = my_api.model('InputDataModel', {
    'customerNumber': fields.String(
        description='Customer number that was stored',
        example='801000000029'
    )
...
})

It adds a parameter to the swagger.json named payload which is just an json-object.
When i use something like this:

 @my_api.doc(
        params={
            'customerNumber': {
                'description': 'Customer ID (required)',
                'in': 'body',
                'type': 'string',
                'required': True,
                'example': '702000000020'
            },

it defines the field properly in the swagger.json. If i add both, i get both, so the sandbox would add a field payload to the outgoing request. I think either expect should create the same fields as using params= does, no? Am i missing something?

Additional context

% pip list | grep -i flask
Flask                     3.0.3
flask-cors                6.0.1
flask-restx               1.3.2
Flask-SQLAlchemy          3.1.1

[MajorDallas]

Ultimately, both decorators call the doc decorator:

    def expect(self, *inputs, **kwargs):
        """
        A decorator to Specify the expected input model

        :param ModelBase|Parse inputs: An expect model or request parser
        :param bool validate: whether to perform validation or not

        """
        expect = []
        params = {"validate": kwargs.get("validate", self._validate), "expect": expect}
        for param in inputs:
            expect.append(param)
        return self.doc(**params)

...

    def param(self, name, description=None, _in="query", **kwargs):
        """
        A decorator to specify one of the expected parameters

        :param str name: the parameter name
        :param str description: a small description
        :param str _in: the parameter location `(query|header|formData|body|cookie)`
        """
        param = kwargs
        param["in"] = _in
        param["description"] = description
        return self.doc(params={name: param})

I have an endpoint that uses both, and your guess is correct: the Swagger schema for it has the settings for both under the path's parameters key. They're two different ways to end up in the same place.

That said, you should use expect over params in most cases. As far as I know, only expect also sets up automatic validation of inputs. I used it because I couldn't find a better way to make it visible that this particular endpoint wants a different Content-Type from nearly every other endpoint.