sc-oa 0.7.0.17__py3-none-any.whl

sc_oa-0.7.0.17.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: sc-oa
+Version: 0.7.0.17
+Summary: Fork of the OpenAPI (fka Swagger) spec renderer for Sphinx
+Home-page: https://github.com/olivier-heurtier/sphinxcontrib-openapi/tree/mymaster
+Author: Olivier Heurtier
+Author-email: olivier.heurtier@github.com
+License: BSD
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: sphinx
+Requires-Dist: sphinxcontrib-httpdomain
+Requires-Dist: PyYAML
+Requires-Dist: jsonschema
+Requires-Dist: m2r2
+Requires-Dist: picobox
+Requires-Dist: deepmerge
+Requires-Dist: setuptools
+Dynamic: license-file

sc_oa-0.7.0.17.dist-info/RECORD

@@ -0,0 +1,26 @@
+sc_oa-0.7.0.17.dist-info/licenses/LICENSE,sha256=Fe9eBZy-tUN-UOMSVfcr4c-MWpuWa4gTKTqH-kSeck4,1319
+sphinxcontrib/__init__.py,sha256=Es10gRADmbGSJZnYYmhfgA_2QzHQDmhj0IAft3kS1Og,259
+sphinxcontrib/openapi/__init__.py,sha256=x8cvrnXGqjZSc62nkeZC0KdCcCSXQY8uxv1kFhrPM18,3088
+sphinxcontrib/openapi/__main__.py,sha256=cp8p7qGn8nH2W_aeD9sMTuqPwLV3ys8DtLYZnyF29pY,2436
+sphinxcontrib/openapi/_lib2to3.py,sha256=mU2Dx78xEyiz0cfcj3R9eqiwHbCfspK5cDJ5ZwwQdA4,13624
+sphinxcontrib/openapi/directive.py,sha256=J4T0n_KkM6SB1Mr9GeYCVqWZNp3BMSjEnVvLvwj8CoM,2059
+sphinxcontrib/openapi/openapi20.py,sha256=FDdlcRIYKCynOZUjxQNoE8lCFRrZinmYu1khz8D18ZU,8984
+sphinxcontrib/openapi/openapi30.py,sha256=zvFih09I9dVY0_YLJmoKSHPz0DynBKbc06rUfbYONWo,29212
+sphinxcontrib/openapi/schema_utils.py,sha256=pxdB5qSTAtiCFmmF04R0zlOOG-Dxi98qwrA2uLZcNXA,4446
+sphinxcontrib/openapi/utils.py,sha256=oRWNDb_5KWTXOVblFgvrLvmGATae8C7PYvk1xc464vY,4343
+sphinxcontrib/openapi/locale/openapi.pot,sha256=sGo7dIRUUS6Ne4MRIU7PCphOoQG1AORgZhwwpD0nRfo,3831
+sphinxcontrib/openapi/locale/es_ES/LC_MESSAGES/openapi.mo,sha256=qdW6yFaSVB_BsexvwM33U8X12yoHikgaI8N7a4U_gI4,1919
+sphinxcontrib/openapi/locale/es_ES/LC_MESSAGES/openapi.po,sha256=dB6_HK0ubCauj1LZbs-zz0NNcPkm4eqKIuxZtqD71WU,4357
+sphinxcontrib/openapi/locale/fr_FR/LC_MESSAGES/openapi.mo,sha256=YS2uZZZ4bHpDXJmShv33NZhtIWcir9-qERusNDR-vqY,1956
+sphinxcontrib/openapi/locale/fr_FR/LC_MESSAGES/openapi.po,sha256=_rpbU9BhwTI2vXFcgj-BdiC-5LhUphYvHtoU1jPHT4Y,4400
+sphinxcontrib/openapi/renderers/__init__.py,sha256=8hdY-sLK5kDbOL8Tqe55xEBphPFXVCNj6eUA3lTvD8s,408
+sphinxcontrib/openapi/renderers/_description.py,sha256=FAklhEaMksCYU5bno3SO0RuQCcwVTXbqPmPN3PrRlTM,702
+sphinxcontrib/openapi/renderers/_httpdomain.py,sha256=qx6pIVQF2BKWjrL1YOap1_2odtLAqk5SeuktofdOMRQ,24546
+sphinxcontrib/openapi/renderers/_httpdomain_old.py,sha256=aiWafD8LdRmCtG6ewkU3xF-P1oWxxYxUNzdcUFW4hB4,2632
+sphinxcontrib/openapi/renderers/_model.py,sha256=yoU265jAgkiW_Ew4EFiWuzA8Q56AsmYa4HBODJDA2bw,15441
+sphinxcontrib/openapi/renderers/_toc.py,sha256=0cVLyKJBcu4ULkiBdlQ-oMBWV4DVCVM5-BgT07xG0Fc,1478
+sphinxcontrib/openapi/renderers/abc.py,sha256=-irO9yVoHeygaMieq4DZMmWD0B5DkDu2mKuenGYopTI,1485
+sc_oa-0.7.0.17.dist-info/METADATA,sha256=4tWFEZMwdtDJ2C76UGcDwj6NcouRccJaJZ_VPo5Uhkg,1312
+sc_oa-0.7.0.17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sc_oa-0.7.0.17.dist-info/top_level.txt,sha256=VJrV3_vaiKQVgVpR0I1iecxoO0drzGu-M0j40PVP2QQ,14
+sc_oa-0.7.0.17.dist-info/RECORD,,

sc_oa-0.7.0.17.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sc_oa-0.7.0.17.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2016, Igor Kalnitsky <igor@kalnitsky.org>.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sc_oa-0.7.0.17.dist-info/top_level.txt

@@ -0,0 +1 @@
+sphinxcontrib

sphinxcontrib/__init__.py

@@ -0,0 +1,10 @@
+"""
+    sphinxcontrib
+    ~~~~~~~~~~~~~
+
+    This package is a namespace package that contains all extensions
+    distributed in the ``sphinx-contrib`` distribution.
+
+    :copyright: (c) 2016 by Igor Kalnitsky.
+    :license: BSD, see LICENSE for details.
+"""

sphinxcontrib/openapi/__init__.py

@@ -0,0 +1,93 @@
+"""get_distribution
+    sphinxcontrib.openapi
+    ---------------------
+
+    The OpenAPI spec renderer for Sphinx. It's a new way to document your
+    RESTful API. Based on ``sphinxcontrib-httpdomain``.
+
+    :copyright: (c) 2016, Ihor Kalnytskyi.
+    :license: BSD, see LICENSE for details.
+"""
+
+import os
+from importlib.metadata import distribution, PackageNotFoundError
+from sphinxcontrib.openapi import renderers, directive
+from sphinx.domains import Domain
+import yaml
+from docutils import nodes
+
+try:
+    __version__ = distribution(__name__).version
+except PackageNotFoundError:
+    # package is not installed
+    __version__ = None
+
+
+_DEFAULT_RENDERER_NAME = "httpdomain:old"
+
+
+def oasversion_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+    fn = text
+    env = inliner.document.settings.env
+    rel_fn, fn = env.relfn2path(fn)
+    y = yaml.load(open(fn, 'r').read(), Loader=yaml.FullLoader)
+    s = y['info']['version']
+    retnode = nodes.inline(text=s, role=typ.lower(), classes=[typ])
+    return [retnode], []
+
+
+class OpenAPIDomain(Domain):
+    name = 'openapi'
+    label = 'OpenAPI Documentation'
+
+    directives = {
+        'httpdomain:old': directive.create_directive_from_renderer(
+            renderers.HttpdomainOldRenderer),
+        'httpdomain': directive.create_directive_from_renderer(renderers.HttpdomainRenderer),
+        'model': directive.create_directive_from_renderer(renderers.ModelRenderer),
+        'toc': directive.create_directive_from_renderer(renderers.TocRenderer),
+        'description': directive.create_directive_from_renderer(renderers.DescriptionRenderer),
+    }
+
+    roles = {
+        'version': oasversion_role
+    }
+
+
+def setup(app):
+    app.add_config_value("openapi_default_renderer", _DEFAULT_RENDERER_NAME, "html")
+    app.add_config_value("openapi_renderers", {}, "html")
+
+    package_dir = os.path.abspath(os.path.dirname(__file__))
+    locale_dir = os.path.join(package_dir, 'locale')
+    app.add_message_catalog('openapi', locale_dir)
+
+    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.add_domain(OpenAPIDomain)
+    app.add_directive(
+        "openapi",
+        directive.create_directive_from_renderer(renderers.HttpdomainOldRenderer)
+    )
+
+    return {"version": __version__, "parallel_read_safe": True}

sphinxcontrib/openapi/__main__.py

@@ -0,0 +1,86 @@
+import argparse
+import logging
+
+from sphinxcontrib.openapi import directive, renderers
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='oas2rst',
+        description='Export OpenAPI Specification files to reStructuredText \
+            files')
+    parser.add_argument(
+        "-l", "--level",
+        action='store',
+        default=logging.INFO,
+        dest='level',
+        help="Logging level")
+    parser.add_argument(
+        "-e", "--encoding",
+        action='store',
+        default="UTF-8",
+        dest='encoding',
+        help="Source file encoding")
+    parser.add_argument(
+        "-p", "--paths",
+        action='append',
+        dest='paths',
+        help="Endpoints to be rendered")
+    parser.add_argument(
+        "-x", "--examples",
+        action='store_true',
+        dest='examples',
+        help="Include examples")
+    parser.add_argument(
+        "--group-examples",
+        action='store_true',
+        dest='group_examples',
+        help="Group examples after the operation description")
+    parser.add_argument(
+        "-E", "--entities",
+        action='store_true',
+        dest='entities',
+        help="Include links to entities")
+    parser.add_argument(
+        "-g", "--group",
+        action='store_true',
+        dest='group',
+        help="Group paths by tag")
+    parser.add_argument(
+        "-i", "--input",
+        dest='input',
+        required=True,
+        help="Input file")
+    parser.add_argument(
+        "-o", "--output",
+        type=argparse.FileType('w'),
+        required=True,
+        dest='output',
+        help="Output file")
+
+    options = parser.parse_args()
+    logging.getLogger().setLevel(options.level)
+
+    openapi_options = {}
+    if options.paths:
+        openapi_options['paths'] = options.paths
+    if options.examples:
+        openapi_options['examples'] = True
+    if options.group_examples:
+        openapi_options['group_examples'] = True
+    if options.entities:
+        openapi_options['entities'] = True
+    if options.group:
+        openapi_options['group'] = True
+
+    openapi_options.setdefault('uri', 'file://%s' % options.input)
+    spec = directive._get_spec(options.input, options.encoding)
+    renderer = renderers.HttpdomainOldRenderer(None, openapi_options)
+
+    for line in renderer.render_restructuredtext_markup(spec):
+        options.output.write(line+'\n')
+        logging.debug(line)
+
+
+if __name__ == '__main__':
+    main()

sphinxcontrib/openapi/_lib2to3.py

@@ -0,0 +1,378 @@
+"""Partial OpenAPI v2.x (fka Swagger) to OpenAPI v3.x converter."""
+
+import functools
+import urllib
+
+import picobox
+
+
+__all__ = [
+    "convert",
+]
+
+
+def convert(spec):
+    """Convert a given OAS 2 spec to OAS 3."""
+
+    return Lib2to3().convert(spec)
+
+
+def _is_vendor_extension(key):
+    """Return 'True' if a given key is a vendor extension."""
+
+    return key.startswith("x-")
+
+
+def _get_properties(node, properties, *, vendor_extensions=False):
+    """Return a subset of 'node' properties w/ or wo/ vendor extensions."""
+
+    return {
+        key: value
+        for key, value in node.items()
+        if any([key in properties, vendor_extensions and _is_vendor_extension(key)])
+    }
+
+
+def _get_schema_properties(node, *, except_for=None):
+    """Find and return 'Schema Object' properties."""
+
+    except_for = except_for or set()
+    schema = _get_properties(
+        node,
+        {
+            "additionalProperties",
+            "allOf",
+            "default",
+            "description",
+            "discriminator",
+            "enum",
+            "example",
+            "exclusiveMaximum",
+            "exclusiveMinimum",
+            "externalDocs",
+            "format",
+            "items",
+            "maxItems",
+            "maxLength",
+            "maxProperties",
+            "maximum",
+            "minItems",
+            "minLength",
+            "minProperties",
+            "minimum",
+            "multipleOf",
+            "pattern",
+            "properties",
+            "readOnly",
+            "required",
+            "title",
+            "type",
+            "uniqueItems",
+            "xml",
+        }
+        - set(except_for),
+    )
+
+    if "discriminator" in schema:
+        schema["discriminator"] = {"propertyName": schema["discriminator"]}
+    return schema
+
+
+def _items_wo_vendor_extensions(node):
+    """Iterate over 'node' properties excluding vendor extensions."""
+
+    for key, value in node.items():
+        if _is_vendor_extension(key):
+            continue
+        yield key, value
+
+
+class Lib2to3:
+
+    _target_version = "3.0.3"
+    _injector = picobox.Stack()
+
+    def _insert_into_injector(name):
+        def decorator(fn):
+            @functools.wraps(fn)
+            def wrapper(self, node, *args, **kwargs):
+                with Lib2to3._injector.push(picobox.Box(), chain=True) as box:
+                    box.put(name, factory=lambda: node, scope=picobox.threadlocal)
+                    return fn(self, node, *args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    def __init__(self):
+        self._schemes = set()
+
+    @_insert_into_injector("spec")
+    def convert(self, spec):
+        # The following OAS 2 fields are ignored and not converted. Mostly due
+        # to the fact that we expect *resolved* spec as input, and most of its
+        # fields are used to group shared (i.e. referenced) objects that will
+        # not exist in the resolved spec.
+        #
+        #  - definitions
+        #  - parameters
+        #  - responses
+        #  - securityDefinitions
+        #  - security
+        #
+        # By no means one must assume that these fields will never be
+        # converted. I simply have no time to work on this, and for
+        # sphixcontrib-openapi purposes it's not actually needed.
+
+        converted = {
+            "info": spec["info"],
+            "openapi": self._target_version,
+            "paths": self.convert_paths(spec["paths"]),
+        }
+        converted.update(
+            _get_properties(spec, {"tags", "externalDocs"}, vendor_extensions=True),
+        )
+
+        servers = self.convert_servers(spec)
+        if servers:
+            converted["servers"] = servers
+
+        return converted
+
+    @_insert_into_injector("paths")
+    def convert_paths(self, paths):
+        converted = _get_properties(paths, {}, vendor_extensions=True)
+
+        for endpoint, path in _items_wo_vendor_extensions(paths):
+            converted[endpoint] = self.convert_path(path)
+
+        return converted
+
+    @_insert_into_injector("path")
+    def convert_path(self, path):
+        converted = _get_properties(path, {}, vendor_extensions=True)
+
+        for key, value in _items_wo_vendor_extensions(path):
+            if key == "parameters":
+                converted[key] = self.convert_parameters(value)
+            else:
+                converted[key] = self.convert_operation(value)
+
+        return converted
+
+    @_insert_into_injector("operation")
+    def convert_operation(self, operation):
+        converted = _get_properties(
+            operation,
+            {
+                "tags",
+                "summary",
+                "description",
+                "externalDocs",
+                "operationId",
+                "deprecated",
+                "security",
+            },
+            vendor_extensions=True,
+        )
+
+        # Memorize every encountered 'schemes'. Since this property does not
+        # exist in OAS 3, it seems the best we can do is to use them in OAS 3
+        # 'servers' object.
+        self._schemes.update(operation.get("schemes", []))
+
+        if "parameters" in operation:
+            parameters = self.convert_parameters(operation["parameters"])
+
+            # Both 'body' and 'formData' parameters are mutually exclusive,
+            # therefore there's no way we may end up with both kinds at once.
+            request_body = self.convert_request_body(operation)
+            request_body = request_body or self.convert_request_body_formdata(operation)
+
+            if parameters:
+                converted["parameters"] = parameters
+
+            if request_body:
+                converted["requestBody"] = request_body
+
+        converted["responses"] = self.convert_responses(operation["responses"])
+        return converted
+
+    @_injector.pass_("spec")
+    def convert_request_body(self, operation, *, spec):
+        # OAS 3 expects an explicitly specified mimetype of the request body.
+        # It's not clear what to do if OAS 2 'consumes' is not defined. Let's
+        # start with a glob pattern and figure out what a better option could
+        # be later on.
+        consumes = operation.get("consumes") or spec.get("consumes") or ["*/*"]
+
+        for parameter in operation["parameters"]:
+            if parameter["in"] == "body":
+                # Since 'requestBody' is completely new and nested object in
+                # OAS 3, it's not clear what should we insert possible vendor
+                # extensions. Thus, let's ignore them until we figure it out.
+                converted = _get_properties(parameter, {"description", "required"})
+                converted["content"] = {
+                    consume: {"schema": parameter["schema"]} for consume in consumes
+                }
+                return converted
+
+        return None
+
+    @_injector.pass_("spec")
+    def convert_request_body_formdata(self, operation, *, spec):
+        consumes = (
+            operation.get("consumes")
+            or spec.get("consumes")
+            or ["application/x-www-form-urlencoded"]
+        )
+        supported = {
+            "application/x-www-form-urlencoded",
+            "multipart/form-data",
+        }
+        mimetypes = supported.intersection(consumes)
+        schema = {"type": "object", "properties": {}}
+
+        for parameter in operation["parameters"]:
+            if parameter["in"] == "formData":
+                schema["properties"][parameter["name"]] = _get_schema_properties(
+                    parameter, except_for={"name", "in", "required"}
+                )
+
+                if parameter.get("required"):
+                    schema.setdefault("required", []).append(parameter["name"])
+
+                # Excerpt from OpenAPI 2.x spec:
+                #
+                # > If type is "file", the consumes MUST be either
+                # > "multipart/form-data", "application/x-www-form-urlencoded"
+                # > or both and the parameter MUST be in "formData".
+                #
+                # This is weird since HTTP does not allow file uploading in
+                # 'application/x-www-form-urlencoded'. Moreover, Swagger
+                # editor complains if 'file' is detected and there's no
+                # 'multipart/form-data' in `consumes'.
+                if parameter["type"] == "file":
+                    mimetypes = ["multipart/form-data"]
+
+        if not schema["properties"]:
+            return None
+        return {"content": {mimetype: {"schema": schema} for mimetype in mimetypes}}
+
+    @_insert_into_injector("parameters")
+    def convert_parameters(self, parameters):
+        return [
+            self.convert_parameter(parameter)
+            for parameter in parameters
+            # If a parameter is one of the backward compatible type, delegate
+            # the call to the converter function. Incompatible types, such as
+            # 'formData' and 'body', must be handled separately since they are
+            # reflected in 'Operation Object' in OAS 3.
+            if parameter["in"] in {"query", "header", "path"}
+        ]
+
+    @_insert_into_injector("parameter")
+    def convert_parameter(self, parameter):
+        schema = _get_schema_properties(
+            parameter,
+            # Some of 'Parameter Object' properties have the same name as some
+            # of 'Schema Object' properties. Since we know for sure that in
+            # this context they are part of 'Parameter Object', we should
+            # ignore their meaning as part of 'Schema Object'.
+            except_for={"name", "in", "description", "required"},
+        )
+        converted = {
+            key: value for key, value in parameter.items() if key not in schema
+        }
+        converted["schema"] = schema
+        collection_format = converted.pop("collectionFormat", None)
+
+        if converted["in"] in {"path", "header"} and collection_format == "csv":
+            converted["style"] = "simple"
+        elif converted["in"] in {"query"} and collection_format:
+            styles = {
+                "csv": {"style": "form", "explode": False},
+                "multi": {"style": "form", "explode": True},
+                "ssv": {"style": "spaceDelimited"},
+                "pipes": {"style": "pipeDelimited"},
+                # OAS 3 does not explicitly say what is the alternative to
+                # 'collectionFormat=tsv'. We have no other option but to ignore
+                # it. Fortunately, we don't care much as it's not used by the
+                # renderer.
+                "tsv": {},
+            }
+            converted.update(styles[collection_format])
+
+        return converted
+
+    @_insert_into_injector("responses")
+    def convert_responses(self, responses):
+        converted = _get_properties(responses, {}, vendor_extensions=True)
+
+        for status_code, response in _items_wo_vendor_extensions(responses):
+            converted[status_code] = self.convert_response(response)
+
+        return converted
+
+    @_injector.pass_("spec")
+    @_injector.pass_("operation")
+    @_insert_into_injector("response")
+    def convert_response(self, response, *, spec, operation):
+        converted = _get_properties(response, {"description"}, vendor_extensions=True)
+
+        # OAS 3 expects an explicitly specified mimetype in the response. It's
+        # not clear what to do if OAS 2 'produces' is not defined. Let's start
+        # with a glob pattern and figure out what a better option could be
+        # later on.
+        produces = operation.get("produces") or spec.get("produces") or ["*/*"]
+        schema = response.get("schema")
+        examples = response.get("examples")
+
+        if schema or examples:
+            content = converted.setdefault("content", {})
+
+            if schema is not None:
+                for mimetype in produces:
+                    content.setdefault(mimetype, {})["schema"] = schema
+
+            if examples is not None:
+                # According to OAS2, mimetypes in 'examples' property MUST be
+                # one of the operation's 'produces'.
+                for mimetype, example in examples.items():
+                    content.setdefault(mimetype, {})["example"] = example
+
+        if "headers" in response:
+            converted["headers"] = {
+                key: dict(
+                    _get_properties(value, "description", vendor_extensions=True),
+                    schema=_get_schema_properties(value, except_for={"description"}),
+                )
+                for key, value in response["headers"].items()
+            }
+
+        return converted
+
+    def convert_servers(self, spec):
+        """Convert OAS2 '(host, basePath, schemes)' triplet into OAS3 'servers' node."""
+
+        host = spec.get("host", "")
+        basepath = spec.get("basePath", "")
+        schemes = self._schemes.union(spec.get("schemes", set()))
+
+        # Since 'host', 'basePath' and 'schemes' are optional in OAS 2, there
+        # may be the case when they aren't set. If that's happened it means
+        # there's nothing to convert, and thus we simply return an empty list.
+        if not host and not basepath and not schemes:
+            return []
+
+        if not schemes:
+            # If 'host' is not set, the url will contain a bare basePath.
+            # According to OAS 3, it's a valid URL, and both the host and the
+            # scheme must be assumed to be the same as the server that shared
+            # this OAS 3 spec.
+            return [{"url": urllib.parse.urljoin(host, basepath)}]
+
+        return [
+            {"url": urllib.parse.urlunsplit([scheme, host, basepath, None, None])}
+            for scheme in sorted(schemes)
+        ]