Add note about ordered Schemas

docs/openapi.rst

@@ -194,6 +194,31 @@ The :meth:`Api.register_converter` allows to register a converter in the
     @blp.route('/pets/{objectid:pet_id}')
         ...
 
+Enforce Field Order in Documentation
+------------------------------------
+
+In the OpenAPI specification file, the fields of a ``Schema`` are documented as
+schema `properties`. Although objects are not ordered in JSON, OpenAPI
+graphical interfaces tend to respect the order in which the `properties` are
+defined in the ``properties`` object in the specification file.
+
+When using an ordererd ``Schema``, the fields definition order is preserved
+when generating the specification file and the `properties` are displayed in
+that order.
+
+This is typically done in a base class:
+
+.. code-block:: python
+    :emphasize-lines: 2,3
+
+    class MyBaseSchema(ma.Schema):
+        class Meta:
+            ordered = True
+
+    class User(MyBaseSchema):
+        name = ma.fields.String()
+        surname = ma.fields.String()
+
 Serve the OpenAPI Documentation
 -------------------------------
 

docs/quickstart.rst

@@ -48,10 +48,6 @@ Define a marshmallow :class:`Schema <marshmallow.Schema>` to expose the model.
 .. code-block:: python
 
     class PetSchema(ma.Schema):
-
-        class Meta:
-            ordered = True
-
         id = ma.fields.Int(dump_only=True)
         name = ma.fields.String()
 
@@ -62,10 +58,6 @@ query arguments.
 .. code-block:: python
 
     class PetQueryArgsSchema(ma.Schema):
-
-        class Meta:
-            ordered = True
-
         name = ma.fields.String()