Merge branch 'master' into master

ziirish · web-flow · commit 009c38e69bf3 · 2020-09-02T21:16:39.000+02:00
diff --git a/doc/conf.py b/doc/conf.py
@@ -52,7 +52,7 @@
 
 # General information about the project.
 project = u"Flask-RESTX"
-copyright = u"2014, Axel Haustant"
+copyright = u"2020, python-restx Authors"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -263,7 +263,7 @@
         "index",
         "Flask-RESTX.tex",
         u"Flask-RESTX Documentation",
-        u"Axel Haustant",
+        u"python-restx Authors",
         "manual",
     ),
 ]
@@ -294,7 +294,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ("index", "flask-restx", u"Flask-RESTX Documentation", [u"Axel Haustant"], 1)
+    ("index", "flask-restx", u"Flask-RESTX Documentation", [u"python-restx Authors"], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -311,7 +311,7 @@
         "index",
         "Flask-RESTX",
         u"Flask-RESTX Documentation",
-        u"Axel Haustant",
+        u"python-restx Authors",
         "Flask-RESTX",
         "One line description of project.",
         "Miscellaneous",
diff --git a/doc/configuration.rst b/doc/configuration.rst
@@ -0,0 +1,65 @@
+Configuration
+=============
+
+Flask-RESTX provides the following `Flask configuration values <https://flask.palletsprojects.com/en/1.1.x/config/#configuration-handling>`_:
+
+    Note: Values with no additional description should be covered in more detail
+    elsewhere in the documentation. If not, please open an issue on GitHub.
+
+.. py:data:: RESTX_JSON
+
+    Provide global configuration options for JSON serialisation as a :class:`dict`
+    of :func:`json.dumps` keyword arguments.
+
+.. py:data:: RESTX_VALIDATE
+
+   Whether to enforce payload validation by default when using the
+   ``@api.expect()`` decorator. See the `@api.expect()
+   <swagger.html#the-api-expect-decorator>`__ documentation for details.
+   This setting defaults to ``False``.
+
+.. py:data:: RESTX_MASK_HEADER
+
+  Choose the name of the *Header* that will contain the masks to apply to your
+  answer. See the `Fields masks <mask.html>`__ documentation for details.
+  This setting defaults to ``X-Fields``.
+
+.. py:data:: RESTX_MASK_SWAGGER
+
+  Whether to enable the mask documentation in your swagger or not. See the
+  `mask usage <mask.html#usage>`__ documentation for details.
+  This setting defaults to ``True``.
+
+.. py:data:: RESTX_INCLUDE_ALL_MODELS
+
+  This option allows you to include all defined models in the generated Swagger
+  documentation, even if they are not explicitly used in either ``expect`` nor
+  ``marshal_with`` decorators.
+  This setting defaults to ``False``.
+
+.. py:data:: BUNDLE_ERRORS
+
+  Bundle all the validation errors instead of returning only the first one
+  encountered. See the `Error Handling <parsing.html#error-handling>`__ section
+  of the documentation for details.
+  This setting defaults to ``False``.
+
+.. py:data:: ERROR_404_HELP
+
+.. py:data:: HTTP_BASIC_AUTH_REALM
+
+.. py:data:: SWAGGER_VALIDATOR_URL
+
+.. py:data:: SWAGGER_UI_DOC_EXPANSION
+
+.. py:data:: SWAGGER_UI_OPERATION_ID
+
+.. py:data:: SWAGGER_UI_REQUEST_DURATION
+
+.. py:data:: SWAGGER_UI_OAUTH_APP_NAME
+
+.. py:data:: SWAGGER_UI_OAUTH_CLIENT_ID
+
+.. py:data:: SWAGGER_UI_OAUTH_REALM
+
+.. py:data:: SWAGGER_SUPPORTED_SUBMIT_METHODS
diff --git a/doc/example.rst b/doc/example.rst
@@ -7,7 +7,7 @@ Here is a full example of a `TodoMVC <http://todomvc.com/>`_ API.
 
     from flask import Flask
     from flask_restx import Api, Resource, fields
-    from werkzeug.contrib.fixers import ProxyFix
+    from werkzeug.middleware.proxy_fix import ProxyFix
 
     app = Flask(__name__)
     app.wsgi_app = ProxyFix(app.wsgi_app)
diff --git a/doc/index.rst b/doc/index.rst
@@ -4,19 +4,36 @@
    contain the root `toctree` directive.
 
 Welcome to Flask-RESTX's documentation!
-==========================================
+=======================================
 
 Flask-RESTX is an extension for Flask that adds support for quickly building REST APIs.
 Flask-RESTX encourages best practices with minimal setup.
 If you are familiar with Flask, Flask-RESTX should be easy to pick up.
 It provides a coherent collection of decorators and tools to describe your API
 and expose its documentation properly (using Swagger).
 
+Flask-RESTX is a community driven fork of `Flask-RESTPlus
+<https://github.com/noirbizarre/flask-restplus>`_
+
+
+Why did we fork?
+================
+
+The community has decided to fork the project due to lack of response from the
+original author @noirbizarre. We have been discussing this eventuality for
+`a long time <https://github.com/noirbizarre/flask-restplus/issues/593>`_.
+
+Things evolved a bit since that discussion and a few of us have been granted
+maintainers access to the github project, but only the original author has
+access rights on the PyPi project. As such, we been unable to make any actual
+releases. To prevent this project from dying out, we have forked it to continue
+development and to support our users.
+
 
 Compatibility
 =============
 
-flask-restx requires Python 2.7+.
+flask-restx requires Python 2.7+ or 3.4+.
 
 
 Installation
@@ -55,6 +72,7 @@ Flask-RESTX with Flask.
     postman
     scaling
     example
+    configuration
 
 
 API Reference
diff --git a/doc/marshalling.rst b/doc/marshalling.rst
@@ -521,7 +521,7 @@ You can define models using `JSON Schema <http://json-schema.org/examples.html>`
         'type': 'object'
     })
 
-    person = address = api.schema_model('Person', {
+    person = api.schema_model('Person', {
         'required': ['address'],
         'properties': {
             'name': {
diff --git a/doc/parsing.rst b/doc/parsing.rst
@@ -249,7 +249,7 @@ and to set the type to :class:`~werkzeug.datastructures.FileStorage`.
             url = do_something_with_file(uploaded_file)
             return {'url': url}, 201
 
-See the `dedicated Flask documentation section <http://flask.pocoo.org/docs/0.10/patterns/fileuploads/>`_.
+See the `dedicated Flask documentation section <https://flask.palletsprojects.com/en/1.1.x/patterns/fileuploads/>`_.
 
 
 Error Handling
diff --git a/doc/quickstart.rst b/doc/quickstart.rst
@@ -10,6 +10,29 @@ and that you have already installed both Flask and Flask-RESTX.
 If not, then follow the steps in the :ref:`installation` section.
 
 
+Migrate from Flask-RESTPlus
+---------------------------
+
+.. warning:: The *migration* commands provided below are for illustration
+             purposes.
+             You may need to adapt them to properly fit your needs.
+             We also recommend you make a backup of your project prior running them.
+
+At this point, Flask-RESTX remains 100% compatible with Flask-RESTPlus' API.
+All you need to do is update your requirements to use Flask-RESTX instead of
+Flask-RESTPlus. Then you need to update all your imports.
+This can be done using something like:
+
+::
+   find . -type f -name "*.py" | xargs sed -i "s/flask_restplus/flask_restx/g"
+
+Finally, you will need to update your configuration options (described `here
+<quickstart.html#configuration>`_). Example:
+
+::
+   find . -type f -name "*.py" | xargs sed -i "s/RESTPLUS_/RESTX_/g"
+
+
 Initialization
 --------------
 
diff --git a/doc/swagger.rst b/doc/swagger.rst
@@ -536,14 +536,13 @@ For ``POST`` and ``PUT`` methods, use the ``body`` keyword argument to specify t
 
 .. code-block:: python
 
-    fields = api.model('MyModel', {
+    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),
     })
 
 
-    @api.model(fields={'name': fields.String, 'age': fields.Integer})
     class Person(fields.Raw):
         def format(self, value):
             return {'name': value.name, 'age': value.age}
@@ -552,11 +551,11 @@ For ``POST`` and ``PUT`` methods, use the ``body`` keyword argument to specify t
     @api.route('/my-resource/<id>', endpoint='my-resource')
     @api.doc(params={'id': 'An ID'})
     class MyResource(Resource):
-        @api.doc(model=fields)
+        @api.doc(model=my_model)
         def get(self, id):
             return {}
 
-        @api.doc(model='MyModel', body=Person)
+        @api.doc(model=my_model, body=Person)
         def post(self, id):
             return {}
 
diff --git a/examples/complex.py b/examples/complex.py
@@ -1,5 +1,5 @@
 from flask import Flask
-from werkzeug.contrib.fixers import ProxyFix
+from werkzeug.middleware.proxy_fix import ProxyFix
 
 from zoo import api
 
diff --git a/examples/todo.py b/examples/todo.py
@@ -1,6 +1,6 @@
 from flask import Flask
 from flask_restx import Api, Resource, fields
-from werkzeug.contrib.fixers import ProxyFix
+from werkzeug.middleware.proxy_fix import ProxyFix
 
 app = Flask(__name__)
 app.wsgi_app = ProxyFix(app.wsgi_app)
diff --git a/examples/todomvc.py b/examples/todomvc.py
@@ -1,6 +1,6 @@
 from flask import Flask
 from flask_restx import Api, Resource, fields
-from werkzeug.contrib.fixers import ProxyFix
+from werkzeug.middleware.proxy_fix import ProxyFix
 
 app = Flask(__name__)
 app.wsgi_app = ProxyFix(app.wsgi_app)
diff --git a/flask_restx/api.py b/flask_restx/api.py
@@ -515,11 +515,11 @@ def endpoint(self, name):
     @property
     def specs_url(self):
         """
-        The Swagger specifications absolute url (ie. `swagger.json`)
+        The Swagger specifications relative url (ie. `swagger.json`)
 
         :rtype: str
         """
-        return url_for(self.endpoint("specs"), _external=True)
+        return url_for(self.endpoint("specs"))
 
     @property
     def base_url(self):
diff --git a/flask_restx/fields.py b/flask_restx/fields.py
@@ -156,7 +156,7 @@ def __init__(
         self.description = description
         self.required = required
         self.readonly = readonly
-        self.example = example or self.__schema_example__
+        self.example = example if example is not None else self.__schema_example__
         self.mask = mask
 
     def format(self, value):
@@ -459,7 +459,7 @@ def format(self, value):
             if value is None:
                 return self.default
             return int(value)
-        except ValueError as ve:
+        except (ValueError, TypeError) as ve:
             raise MarshallingError(ve)
 
 
@@ -473,7 +473,7 @@ class Float(NumberMixin, Raw):
     def format(self, value):
         try:
             return float(value)
-        except ValueError as ve:
+        except (ValueError, TypeError) as ve:
             raise MarshallingError(ve)
 
 
diff --git a/flask_restx/reqparse.py b/flask_restx/reqparse.py
@@ -307,7 +307,6 @@ def __schema__(self):
             param["collectionFormat"] = "csv"
         if self.choices:
             param["enum"] = self.choices
-            param["collectionFormat"] = "multi"
         return param
 
 
diff --git a/flask_restx/swagger.py b/flask_restx/swagger.py
@@ -657,6 +657,8 @@ def register_model(self, model):
         if name not in self.api.models:
             raise ValueError("Model {0} not registered".format(name))
         specs = self.api.models[name]
+        if name in self._registered_models:
+            return ref(model)
         self._registered_models[name] = specs
         if isinstance(specs, ModelBase):
             for parent in specs.__parents__:
diff --git a/tests/test_fields.py b/tests/test_fields.py
@@ -276,10 +276,14 @@ def test_with_default(self):
     def test_value(self, value, expected):
         self.assert_field(fields.Integer(), value, expected)
 
-    def test_decode_error(self):
+    def test_decode_error_on_invalid_value(self):
         field = fields.Integer()
         self.assert_field_raises(field, "an int")
 
+    def test_decode_error_on_invalid_type(self):
+        field = fields.Integer()
+        self.assert_field_raises(field, {"a": "dict"})
+
 
 class BooleanFieldTest(BaseFieldTestMixin, FieldTestCase):
     field_class = fields.Boolean
@@ -294,6 +298,14 @@ def test_with_default(self):
         assert not field.required
         assert field.__schema__ == {"type": "boolean", "default": True}
 
+    def test_with_example(self):
+        field = fields.Boolean(default=True, example=False)
+        assert field.__schema__ == {
+            "type": "boolean",
+            "default": True,
+            "example": False,
+        }
+
     @pytest.mark.parametrize(
         "value,expected",
         [
@@ -330,10 +342,14 @@ def test_value(self, value, expected):
     def test_raises(self):
         self.assert_field_raises(fields.Float(), "bar")
 
-    def test_decode_error(self):
+    def test_decode_error_on_invalid_value(self):
         field = fields.Float()
         self.assert_field_raises(field, "not a float")
 
+    def test_decode_error_on_invalid_type(self):
+        field = fields.Float()
+        self.assert_field_raises(field, {"a": "dict"})
+
 
 PI_STR = (
     "3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117"
diff --git a/tests/test_reqparse.py b/tests/test_reqparse.py
@@ -943,7 +943,6 @@ def test_choices(self):
                 "type": "string",
                 "in": "query",
                 "enum": ["a", "b"],
-                "collectionFormat": "multi",
             }
         ]
 
diff --git a/tests/test_swagger.py b/tests/test_swagger.py
@@ -2057,6 +2057,27 @@ def get(self):
 
         client.get_specs(status=500)
 
+    def test_recursive_model(self, api, client):
+        fields = api.model('Person', {
+            'name': restx.fields.String,
+            'age': restx.fields.Integer,
+            'birthdate': restx.fields.DateTime,
+        })
+
+        fields["children"] = restx.fields.List(
+            restx.fields.Nested(fields),
+            default=[],
+        )
+
+        @api.route('/recursive-model/')
+        @api.doc(get={'model': fields})
+        class ModelAsDict(restx.Resource):
+            @api.marshal_with(fields)
+            def get(self):
+                return {}
+
+        client.get_specs(status=200)
+
     def test_specs_no_duplicate_response_keys(self, api, client):
         """
         This tests that the swagger.json document will not be written with duplicate object keys
