Broken code in configuration

[ybizeul]

I'm seriously going through a lot of frustration trying to figure out the documentation, let alone figure out the whole thing...

This is from the documentation :

fields = api.model('MyModel', {
    'name': fields.String(description='The name', required=True),
    'type': fields.String(description='The object type', enum=['A', 'B']),
    'age': fields.Integer(min=0),
})

@api.model(fields={'name': fields.String, 'age': fields.Integer})
class Person(fields.Raw):
    def format(self, value):
        return {'name': value.name, 'age': value.age}

First we declare fields which end up being a Model

Then on the next block, we happily use fields.String, fields.Integer, etc which I think are imported from flask_restx

So I went ahead and delete the fields declaration, thinking it's yet another place in the doc when they list alternatives but they wouldn't say so...

It ended up worse :

@api.model(fields={'name': fields.String, 'age': fields.Integer})
class Person(fields.Raw):
    def format(self, value):
        return {'name': value.name, 'age': value.age}

Traceback (most recent call last):
  File "/usr/local/bin/flask", line 8, in <module>
    sys.exit(main())
  File "/usr/local/lib/python3.8/site-packages/flask/cli.py", line 967, in main
    cli.main(args=sys.argv[1:], prog_name="python -m flask" if as_module else None)
  File "/usr/local/lib/python3.8/site-packages/flask/cli.py", line 586, in main
    return super(FlaskGroup, self).main(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/click/decorators.py", line 73, in new_func
    return ctx.invoke(f, obj, *args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/flask/cli.py", line 848, in run_command
    app = DispatchingApp(info.load_app, use_eager_loading=eager_loading)
  File "/usr/local/lib/python3.8/site-packages/flask/cli.py", line 305, in __init__
    self._load_unlocked()
  File "/usr/local/lib/python3.8/site-packages/flask/cli.py", line 330, in _load_unlocked
    self._app = rv = self.loader()
  File "/usr/local/lib/python3.8/site-packages/flask/cli.py", line 388, in load_app
    app = locate_app(self, import_name, name)
  File "/usr/local/lib/python3.8/site-packages/flask/cli.py", line 240, in locate_app
    __import__(module_name)
  File "/app/api.py", line 50, in <module>
    @api.model(fields={'name': fields.String, 'age': fields.Integer})
  File "/usr/local/lib/python3.8/site-packages/flask_restx/namespace.py", line 172, in model
    model = cls(name, model, mask=mask)
  File "/usr/local/lib/python3.8/site-packages/flask_restx/model.py", line 143, in __init__
    super(RawModel, self).__init__(name, *args, **kwargs)
  File "/usr/local/lib/python3.8/site-packages/flask_restx/model.py", line 46, in __init__
    super(ModelBase, self).__init__(*args, **kwargs)
TypeError: 'NoneType' object is not iterable

What am I doing wrong ?

I've seen other mistakes in the doc coming from copy and paste from RestPlus, that's when I figured I will have to fight that thing.

I'm happy to help if I can, but honestly I can't even figure out the documentation, let alone fix it.

[SteadBytes]

There seems to be several issues here:

1. The example given in the documentation is broken; the model assigned to the fields variable shadows the flask_restx.fields module:

>>> from flask import Flask
>>> from flask_restx import Api, Resource, fields

>>> app = Flask(__name__)
>>> api = Api(app)

>>> # Shadow the imported fields module
... fields = api.model(
...     "MyModel", {"name": fields.String(description="The name", required=True)}
... )
>>> # Attempts to access one of the flask_restx.fields types fails with an
... # AttributeError as fields actually refers to the Model defined above
... fields.String()
Traceback (most recent call last):
  File "<stdin>", line 3, in <module>
AttributeError: 'Model' object has no attribute 'String'

This can be resolved by removing the fields model declaration as you have done, or by renaming it:

>>> # Rename the model
... my_model = api.model(
...     "MyModel", {"name": fields.String(description="The name", required=True)}
... )

>>> # All good
... fields.String()
<flask_restx.fields.String object at 0x7febd7c0c690>

2. The @api.model usage is (as far as I can tell) completely incorrect. Looking through the Git history I can't see how it ever would have worked. The best guess I've got is that it was intended to demonstrate the following use case and the original author got confused:

        # Renamed to avoid shadowing
        my_model = api.model('MyModel', {
            'name': fields.String(description='The name', required=True),
            'type': fields.String(description='The object type', enum=['A', 'B']),
            'age': fields.Integer(min=0),
        })

        # No @api.model decorator
        class Person(fields.Raw):
            def format(self, value):
                return {'name': value.name, 'age': value.age}

        @api.route('/my-resource/<id>', endpoint='my-resource')
        @api.doc(params={'id': 'An ID'})
        class MyResource(restx.Resource):
            @api.doc(model=my_model)
            def get(self, id):
                return {}

            @api.doc(model='MyModel', body=Person)
            def post(self, id):
                return {}

I do apologise for the confusing documentation. It was not maintained well before forking the project and we haven't had much time to go through and fix it up.

Please let me know if this helps.

[SteadBytes]

I've opened #130 to correct the docs, just waiting for a fellow maintainer to 👍 it just in case I've missed a use case that they're aware of.