diff --git a/docs/openapi.rst b/docs/openapi.rst index 09e99cee..0273f1a1 100644 --- a/docs/openapi.rst +++ b/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 ------------------------------- diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 913321af..46c265cb 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -48,10 +48,6 @@ Define a marshmallow :class:`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()