Flask-RESTX Models Re-Design

[SteadBytes]

For quite some time there have been significant issues around data models, request parsing and response marshalling in flask-restx (carried over from flask-restplus). The most obvious of which is the deprecation warning about the reqparse module in the documentation that has been in place for far too long. These changes have been put off for various reasons which I won't discuss here, however now the new fork is steadily underway I (and no doubt others) would like to start addressing this.

Since this digs quite deep into the architecture of flask-restx there will be significant (and likely breaking) changes required. As such, this issue is to serve as a discussion around the API we would like to provide and some initial ideas of how to best proceed. This is not intended to be the starting point of hacking something together which makes things worse!

I will set out my current thoughts on the topic, please contribute by adding more points and expanding on mine with more discussion.

High Level Goals:

• Uniform API for request parsing and response marshalling
  • e.g. remove the separation between reqparse and models
• Generate correct and valid Swagger/OpenAPI Specifications
• Validation of input and output data should conform to the generated Swagger/OpenAPI Specifications
  • e.g. If the Swagger/OpenAPI spec considers a value valid, the model should too.
• Define models using JSON Schema
  • Supported already, but with numerous issues (@j5awry has been battling for some time)
• OpenAPI 3 support

General Issues/Discussion Points

• What should the API look like?
  • Continue with the api.marshal , api.doc decorator style?
  • How to define models?
  • Do we force direct usage of another library e.g. Marshmallow or wrap in some other API and use the library for the "under the hood" work?
• Model validation
  • External libraries e.g. Marshmallow
• Schema Generation
  • External libraries e.g. Marshmallow
• Backwards compatibility
  • Continue to support reqparse and existing models interface?
  • Swagger 2.0 vs OpenAPI 3.0
  • IMO generating both should be a goal if possible

Resources/Notable Libraries

• https://marshmallow.readthedocs.io/en/stable/
• https://github.com/fuhrysteve/marshmallow-jsonschema
• https://pydantic-docs.helpmanual.io/
• Faust Models, Serialization and Codecs https://faust.readthedocs.io/en/latest/userguide/models.html
  • Faust is not a Flask or even REST library but I have found it's Models to be a nice interface to use.
• https://github.com/apryor6/flask_accepts
• Swagger 2.0 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
• OpenAPI 3.0 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

[peter-doggart]

Hey all.

I've been thinking a lot about how best to deal with changes to models in flask-restx.

My initial thoughts are to leave the underlying structure of the project the way it is, at least for now, mainly for backwards compat and also to avoid introducing new dependencies on other libraries.

With that in mind, I kind of like the idea of offering adapters to go between commonly used external libraries (marshmallow, pydantic etc) and restx models, probably integrating @ClimenteA 's code/ideas from this thread as a starting point.

The aim would be ultimately that you can do api.model.from_<your_library>(external_model) anytime you needed a restx type model (with support for marshalling etc).

That being said, I'm open to ideas if anyone else has a strong opinion on a different path!?

All the best, Pete