Skip to content

Commit

Permalink
Docs: clarify docs about ordered Schemas and Py3.6/3.7
Browse files Browse the repository at this point in the history
  • Loading branch information
lafrech committed Sep 16, 2019
1 parent d6b9118 commit 3f7cae6
Showing 1 changed file with 7 additions and 4 deletions.
11 changes: 7 additions & 4 deletions docs/openapi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,11 @@ The :meth:`Api.register_converter` allows to register a converter in the
Enforce Order in OpenAPI Specification File
-------------------------------------------

When a :class:`Blueprint <Blueprint>` is registered, a `tag` is created with
the ``Blueprint`` name. The display order in the interface is the ``Blueprint``
registration order. And the display order inside a `tag` is the order in which
the resources are defined in the ``Blueprint``.

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
Expand All @@ -219,10 +224,8 @@ This is typically done in a base class:
name = ma.fields.String()
surname = ma.fields.String()
Also, when a :class:`Blueprint <Blueprint>` is registered, a `tag` is created
with the ``Blueprint`` name. The display order in the interface is the
``Blueprint`` registration order. And the display order inside a `tag` is the
order in which the resources are defined in the ``Blueprint``.
Passing ``ordered`` Meta attribute is not necessary when using a Python version
for which dictionaries are always ordered (>= 3.7 or CPyhton 3.6).

Serve the OpenAPI Documentation
-------------------------------
Expand Down

0 comments on commit 3f7cae6

Please sign in to comment.