Merge branch 'master' into json-example

Author: olivier-heurtier

.github/workflows/tests.yml

@@ -24,7 +24,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: [3.5, 3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8]
 
     runs-on: ${{ matrix.os }}
     steps:

.gitignore

@@ -47,6 +47,9 @@ docs/_build/
 *.sublime-project
 *.sublime-workspace
 
+# Ignore VSCode folder
+/.vscode/
+
 # Ignore virtualenvs (who places it near)
 .venv/
 

docs/index.rst

@@ -100,9 +100,36 @@ The ``openapi`` directive supports the following options:
   Would render ``/persons`` and ``/evidence`` endpoints, but not
   ``/evidence/{pk}`` endpoints
 
+``methods``
+  A line separated list of http methods to filter included openapi
+  spec. For example:
+
+  .. code:: restructuredtext
+
+     .. openapi:: specs/openapi.yml
+        :methods:
+            get
+            post
+            put
+        :encoding: utf-8
+
+  Would render paths with get, post or put method
+
 ``exclude``, ``include`` and ``paths`` can also be used together (``exclude``
 taking precedence over ``include`` and ``paths``)
 
+``http-methods-order``
+  A whitespace delimited list of HTTP methods to render first. For example:
+
+  .. code:: restructuredtext
+
+     .. openapi:: specs/openapi.yml
+        :http-methods-order:
+            head
+            get
+
+  Would render the ``head`` method, followed by the ``get`` method, followed by the rest of the methods in their declared ordered.
+
 
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _OpenAPI: https://github.com/OAI/OpenAPI-Specification

setup.py

@@ -47,7 +47,6 @@
         "Programming Language :: Python",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3 :: Only",
-        "Programming Language :: Python :: 3.5",
         "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
@@ -57,5 +56,5 @@
         "Framework :: Sphinx :: Extension",
     ],
     namespace_packages=["sphinxcontrib"],
-    python_requires=">=3.5",
+    python_requires=">=3.6",
 )

sphinxcontrib/openapi/__init__.py

@@ -20,6 +20,7 @@
 
 
 _BUILTIN_RENDERERS = {
+    "httpdomain": renderers.HttpdomainRenderer,
     "httpdomain:old": renderers.HttpdomainOldRenderer,
 }
 _DEFAULT_RENDERER_NAME = "httpdomain:old"
@@ -54,6 +55,27 @@ def setup(app):
     app.add_config_value("openapi_default_renderer", _DEFAULT_RENDERER_NAME, "html")
     app.add_config_value("openapi_renderers", {}, "html")
 
+    from sphinxcontrib import httpdomain
+
+    for idx, fieldtype in enumerate(httpdomain.HTTPResource.doc_field_types):
+        if fieldtype.name == 'requestheader':
+            httpdomain.HTTPResource.doc_field_types[idx] = httpdomain.TypedField(
+                fieldtype.name,
+                label=fieldtype.label,
+                names=fieldtype.names,
+                typerolename='header',
+                typenames=('reqheadertype', ),
+            )
+
+        if fieldtype.name == 'responseheader':
+            httpdomain.HTTPResource.doc_field_types[idx] = httpdomain.TypedField(
+                fieldtype.name,
+                label=fieldtype.label,
+                names=fieldtype.names,
+                typerolename='header',
+                typenames=('resheadertype', ),
+            )
+
     app.setup_extension("sphinxcontrib.httpdomain")
     app.connect("config-inited", _register_rendering_directives)
 

sphinxcontrib/openapi/directive.py

@@ -8,35 +8,19 @@
     :license: BSD, see LICENSE for details.
 """
 
-import collections
 import functools
 
 from docutils.parsers.rst import directives
 from sphinx.util.docutils import SphinxDirective
 import yaml
 
 
-# Dictionaries do not guarantee to preserve the keys order so when we load
-# JSON or YAML - we may loose the order. In most cases it's not important
-# because we're interested in data. However, in case of OpenAPI spec it'd
-# be really nice to preserve them since, for example, endpoints may be
-# grouped logically and that improved readability.
-class _YamlOrderedLoader(yaml.SafeLoader):
-    pass
-
-
-_YamlOrderedLoader.add_constructor(
-    yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
-    lambda loader, node: collections.OrderedDict(loader.construct_pairs(node))
-)
-
-
 # Locally cache spec to speedup processing of same spec file in multiple
 # openapi directives
 @functools.lru_cache()
 def _get_spec(abspath, encoding):
     with open(abspath, 'rt', encoding=encoding) as stream:
-        return yaml.load(stream, _YamlOrderedLoader)
+        return yaml.safe_load(stream)
 
 
 def create_directive_from_renderer(renderer_cls):

sphinxcontrib/openapi/openapi20.py

@@ -104,7 +104,7 @@ def _convert(schema, name='', required=False):
 
         type_ = schema.get('type', 'any')
         required_properties = schema.get('required', ())
-        if type_ == 'object':
+        if type_ == 'object' and schema.get('properties'):
             for prop, next_schema in schema.get('properties', {}).items():
                 _convert(
                     next_schema, '{name}.{prop}'.format(**locals()),
@@ -231,6 +231,8 @@ def openapihttpdomain(spec, **options):
 
         for endpoint in paths:
             for method, properties in spec['paths'][endpoint].items():
+                if options.get('methods') and method not in options.get('methods'):
+                    continue
                 key = properties.get('tags', [''])[0]
                 groups.setdefault(key, []).append(_httpresource(
                     endpoint,
@@ -249,6 +251,8 @@ def openapihttpdomain(spec, **options):
     else:
         for endpoint in paths:
             for method, properties in spec['paths'][endpoint].items():
+                if options.get('methods') and method not in options.get('methods'):
+                    continue
                 generators.append(_httpresource(
                     endpoint,
                     method,

sphinxcontrib/openapi/openapi30.py

@@ -9,7 +9,10 @@
 """
 
 import copy
+
 import collections
+import collections.abc
+
 from datetime import datetime
 import itertools
 import json
@@ -64,9 +67,9 @@ def _dict_merge(dct, merge_dct):
         dct: dict onto which the merge is executed
         merge_dct: dct merged into dct
     """
-    for k, v in merge_dct.items():
+    for k in merge_dct.keys():
         if (k in dct and isinstance(dct[k], dict)
-                and isinstance(merge_dct[k], collections.Mapping)):
+                and isinstance(merge_dct[k], collections.abc.Mapping)):
             _dict_merge(dct[k], merge_dct[k])
         else:
             dct[k] = merge_dct[k]
@@ -105,11 +108,17 @@ def _parse_schema(schema, method):
     schema_type = schema.get('type', 'object')
 
     if schema_type == 'array':
-        # special case oneOf so that we can show examples for all possible
-        # combinations
+        # special case oneOf and anyOf so that we can show examples for all
+        # possible combinations
         if 'oneOf' in schema['items']:
             return [
-                _parse_schema(x, method) for x in schema['items']['oneOf']]
+                _parse_schema(x, method) for x in schema['items']['oneOf']
+            ]
+
+        if 'anyOf' in schema['items']:
+            return [
+                _parse_schema(x, method) for x in schema['items']['anyOf']
+            ]
 
         return [_parse_schema(schema['items'], method)]
 
@@ -181,7 +190,8 @@ def _example(media_type_objects, method=None, endpoint=None, status=None,
         if examples is None:
             examples = {}
             if not example:
-                if content_type != 'application/json':
+                if re.match(r"application/[a-zA-Z\+]*json", content_type) is \
+                        None:
                     LOG.info('skipping non-JSON example generation.')
                     continue
                 example = _parse_schema(content['schema'], method=method)

sphinxcontrib/openapi/renderers/__init__.py

@@ -2,9 +2,11 @@
 
 from . import abc
 from ._httpdomain_old import HttpdomainOldRenderer
+from ._httpdomain import HttpdomainRenderer
 
 
 __all__ = [
     "abc",
     "HttpdomainOldRenderer",
+    "HttpdomainRenderer",
 ]