Code

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

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

model = api.model('Model', {'foo': fields.String})


# @api.route('/get-one')
# @api.doc(model=model)
# class One(Resource):
#     def get(self):
#         return {'foo': "bar"}


@api.route('/get-many')
@api.doc(model=fields.List(fields.Nested(model)))
class Many(Resource):
    def get(self):
        return [{'foo': "bar"}]


if __name__ == '__main__':
    app.run(debug=True)

Expected Behavior

The Swagger doc page should show the get-many endpoint with Model used for the response documentation. Model should appear in the list of models at the end.

Actual Behavior

Model is not included in the list of models, and when the endpoint is expanded, an error is displayed:

Resolver error at paths./get-many.get.responses.200.schema.items.$ref
Could not resolve reference: Could not resolve pointer: /definitions/Model does not exist in document

Environment

• Python version: 3.10
• Flask version: 2.3.2
• Flask-RESTX version: 1.3.0

Additional Context

If the get-one endpoint is uncommented, the behavior is as expected. The cause of the error is in serialize_schema in swagger.py, which gets called to serialize the documentation for the model argument. When a model is passed, it is correctly registered, as well as any nested models. However, if a fields.List(fields.Nested(model)) is passed like in the example, the nested model isn't included. The easiest fix is to include a call to register_field(model) for fields, which
is also called to detect models nested inside other models. I will open a pull request with the proposed solution.

A similar problem goes for the body parameter of api.doc, which documents the expected data (corresponding to api.expect). However, the arguments allowed for model aren't all covered by body. For example, model allows to specify models via their name as a string, while body doesn't. This problem of inconsistent handling is touched upon in #56.

A workaround is to use RESTX_INCLUDE_ALL_MODELS, which includes all defined models in the Swagger doc, regardless of actual usage.