Eve-Swagger 0.2.1__py3-none-any.whl

eve_swagger/__init__.py

@@ -0,0 +1,11 @@
+"""
+eve-swagger
+~~~~~~~~~~~
+swagger.io extension for Eve-powered REST APIs.
+
+:copyright: (c) 2015 by Nicola Iarocci.
+:license: BSD, see LICENSE for more details.
+"""
+
+from .swagger import get_swagger_blueprint, add_documentation  # noqa
+from .definitions import INFO, HOST  # noqa

eve_swagger/definitions.py

@@ -0,0 +1,283 @@
+"""
+eve-swagger.definitions
+~~~~~~~~~~~~~~~~~~~~~~~
+swagger.io extension for Eve-powered REST APIs.
+
+:copyright: (c) 2016 by Nicola Iarocci.
+:license: BSD, see LICENSE for more details.
+"""
+
+from collections import OrderedDict
+from flask import current_app as app
+
+INFO = "SWAGGER_INFO"
+HOST = "SWAGGER_HOST"
+
+
+def definitions():
+    definitions = OrderedDict()
+    dr_sources = {}
+    for rd in app.config["DOMAIN"].values():
+        dr_sources.update(_get_dr_sources(rd["schema"]))
+
+    for rd in app.config["DOMAIN"].values():
+        if rd.get("disable_documentation"):
+            continue
+        title = rd["item_title"]
+        definitions[title] = _object(rd, dr_sources)
+        if "description" in rd:
+            definitions[title]["description"] = rd["description"]
+
+    # add data_relation source fields to #/components/schemas/
+    definitions.update(dr_sources)
+    # add default error response eve schema
+    error_schema = {
+        "type": "object",
+        "properties": {
+            "_status": {"type": "string", "example": "OK"},
+            "_error": {
+                "type": "object",
+                "properties": {
+                    "code": {"type": "integer"},
+                    "message": {"type": "string"},
+                },
+            },
+        },
+        "required": ["_status", "_error"],
+    }
+    definitions["Error"] = error_schema
+    # add default meta response eve schema
+    response_metadata_schema = {
+        "type": "object",
+        "properties": {
+            "page": {"type": "string"},
+            "total": {"type": "integer"},
+            "max_results": {"type": "integer"},
+        },
+    }
+    definitions["response_metadata"] = response_metadata_schema
+
+    response_links_schema = {
+        "type": "object",
+        "properties": {
+            "parent": {
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "format": "uri"},
+                    "href": {"type": "string", "format": "uri"},
+                },
+            },
+            "self": {
+                "type": "object",
+                "properties": {
+                    "title": {"type": "string", "format": "uri"},
+                    "href": {"type": "string", "format": "uri"},
+                },
+            },
+        },
+    }
+
+    definitions["response_links"] = response_links_schema
+
+    return definitions
+
+
+def _object(rd, dr_sources):
+    props = {}
+    required = []
+    for field, rules in rd["schema"].items():
+        if rules.get("required") is True:
+            required.append(field)
+
+        def_name = rd["item_title"] + "_" + field
+        props[field] = _field_props(rules, dr_sources, def_name)
+
+        if def_name in dr_sources:
+            # the current field is a source of a data_relation
+
+            # replace None in dr_sources with the field properties
+            dr_sources[def_name] = OrderedDict(props[field])
+            props[field] = {"$ref": "#/components/schemas/{}".format(def_name)}
+
+        if "data_relation" in rules:
+            # the current field is a copy of another field
+            dr = rules["data_relation"]
+            if dr["resource"] not in app.config["DOMAIN"]:
+                # source of data_relation does not exist
+                continue
+            title = app.config["DOMAIN"][dr["resource"]]["item_title"]
+            source_def_name = title + "_" + dr["field"]
+            props[field] = {"$ref": "#/components/schemas/{}".format(source_def_name)}
+
+    field_def = {}
+    field_def["type"] = "object"
+    field_def["properties"] = props
+    if len(required):
+        field_def["required"] = required
+    return field_def
+
+
+def _field_props(rules, dr_sources, prefix):
+    resp = {}
+    map = {
+        "dict": ("object",),
+        "list": ("array",),
+        "objectid": ("string", "objectid"),
+        "datetime": ("string", "date-time"),
+        "float": ("number", "float"),
+        "point": ("geometry", "Point"),
+        "multipoint": ("geometry", "MultiPoint"),
+        "linestring": ("geometry", "LineString"),
+        "multilinestring": ("geometry", "MultiLineString"),
+        "polygon": ("geometry", "Polygon"),
+        "multipolygon": ("geometry", "MultiPolygon"),
+        "geometrycollection": ("geometry", "GeometryCollection"),
+    }
+    if app.config["RETURN_MEDIA_AS_URL"]:
+        map["media"] = ("string",)
+    else:
+        map["media"] = ("string", "base64")
+
+    eve_type = rules.get("type")
+    if eve_type is None:
+        return resp
+
+    if "description" in rules:
+        resp["description"] = rules["description"]
+
+    if "example" in rules:
+        resp["example"] = rules["example"]
+
+    if "allowed" in rules:
+        resp["enum"] = rules["allowed"]
+
+    if "default" in rules:
+        resp["default"] = rules["default"]
+
+    if "minlength" in rules:
+        if eve_type == "string":
+            resp["minLength"] = rules["minlength"]
+        elif eve_type == "list":
+            resp["minItems"] = rules["minlength"]
+
+    if "maxlength" in rules:
+        if eve_type == "string":
+            resp["maxLength"] = rules["maxlength"]
+        elif eve_type == "list":
+            resp["maxItems"] = rules["maxlength"]
+
+    if "min" in rules:
+        if eve_type in ["number", "integer", "float"]:
+            resp["minimum"] = rules["min"]
+
+    if "max" in rules:
+        if eve_type in ["number", "integer", "float"]:
+            resp["maximum"] = rules["max"]
+
+    if "readonly" in rules:
+        resp["readOnly"] = rules["readonly"]
+
+    if "regex" in rules:
+        resp["pattern"] = rules["regex"]
+
+    if "nullable" in rules:
+        resp["nullable"] = rules["nullable"]
+
+    type = map.get(eve_type, (eve_type,))
+
+    resp["type"] = type[0]
+    if type[0] == "object":
+        if "schema" in rules:
+            # set prefix as item_title to avoid name collisions of nested
+            # fields with higher up fields
+            pseudo_rd = {"item_title": prefix, "schema": rules["schema"]}
+            resp.update(_object(pseudo_rd, dr_sources))
+        # TODO add support for more elaborate cases using additionalProperties
+        elif "valueschema" in rules:
+            keytype = {"type": "string"}
+            if "keyschema" in rules:
+                keytype = rules["keyschema"]
+
+            pseudo_rd = {
+                "item_title": prefix,
+                "properties": {"keys": keytype, "values": rules["valueschema"]},
+            }
+            resp.update(pseudo_rd)
+    elif type[0] == "array":
+        type = "array"
+        if "schema" in rules:
+            resp["items"] = _field_props(rules["schema"], dr_sources, prefix)
+        else:
+            # 'items' is mandatory for swagger, we assume it's a list of
+            # strings
+            resp["items"] = {"type": "string"}
+    elif type[0] == "geometry":
+        # create a pseudo object
+        pseudo_rd = {
+            "item_title": prefix,
+            "schema": {
+                "type": {"type": "string", "allowed": [type[1]], "required": True},
+                "coordinates": {"type": "list", "required": True},
+            },
+        }
+        point2D_rd = {"schema": {"type": "integer"}, "minlength": 2, "maxlength": 2}
+        array_rd = {"schema": {"type": "list"}}
+        s = "schema"
+        c = "coordinates"
+        if type[1] == "Point":
+            # 1st level array of point 2D
+            pseudo_rd[s][c].update(point2D_rd)
+        elif type[1] in ["LineString", "MultiPoint"]:
+            # 2nd level array of point 2D
+            pseudo_rd[s][c].update(array_rd)
+            pseudo_rd[s][c][s].update(point2D_rd)
+        elif type[1] in ["MultiLineString", "Polygon"]:
+            # 3rd level array of point 2D
+            pseudo_rd[s][c].update(array_rd)
+            pseudo_rd[s][c][s].update(array_rd)
+            pseudo_rd[s][c][s][s].update(point2D_rd)
+        elif type[1] in ["MultiPolygon"]:
+            # 4th level array of point 2D
+            pseudo_rd[s][c].update(array_rd)
+            pseudo_rd[s][c][s].update(array_rd)
+            pseudo_rd[s][c][s][s].update(array_rd)
+            pseudo_rd[s][c][s][s][s].update(point2D_rd)
+        elif type[1] in ["GeometryCollection"]:
+            # GeometryCollection require external defs
+            pass
+        resp.update(_object(pseudo_rd, dr_sources))
+    else:
+        try:
+            resp["format"] = type[1]
+        except IndexError:
+            pass
+
+    return resp
+
+
+def _get_dr_sources(schema):
+    """
+    Returns a dict of names for sources of data_relations:
+
+    e.g. the name field in the user resource relates to (is a copy of) the
+    name field of the person resource
+    => return {'person_name': None}
+    """
+    dr_sources = {}
+    for rules in schema.values():
+        if "data_relation" in rules:
+            dr = rules["data_relation"]
+            if dr["resource"] not in app.config["DOMAIN"]:
+                # source of data_relation does not exist
+                continue
+            title = app.config["DOMAIN"][dr["resource"]]["item_title"]
+            def_name = title + "_" + dr["field"]
+            dr_sources[def_name] = None
+        elif "schema" in rules:
+            if rules.get("type") in "dict":
+                # recursively handle data_relations in subdicts
+                dr_sources.update(_get_dr_sources(rules["schema"]))
+            elif rules.get("type") == "list" and "schema" in rules["schema"]:
+                # recursively handle data_relations in lists
+                dr_sources.update(_get_dr_sources(rules["schema"]["schema"]))
+    return dr_sources

eve_swagger/objects.py

@@ -0,0 +1,313 @@
+"""
+eve-swagger.objects
+~~~~~~~~~~~~~~~~~~~
+swagger.io extension for Eve-powered REST APIs.
+
+:copyright: (c) 2015 by Nicola Iarocci.
+:license: BSD, see LICENSE for more details.
+"""
+
+import sys
+from collections import OrderedDict
+from flask import request, current_app as app
+from eve.auth import BasicAuth, TokenAuth
+
+from .validation import validate_info
+from .paths import get_ref_schema
+from .definitions import INFO, HOST
+
+
+def info():
+    validate_info()
+
+    cfg = app.config[INFO]
+
+    def node(parent, cfg, key):
+        value = cfg.get(key)
+        if value:
+            parent[key] = cfg[key]
+
+    info = OrderedDict()
+    node(info, cfg, "title")
+    node(info, cfg, "description")
+    node(info, cfg, "termsOfService")
+    node(info, cfg, "contact")
+    node(info, cfg, "license")
+    node(info, cfg, "version")
+
+    return info
+
+
+def servers():
+    url = app.config.get(HOST) or "%s://%s" % (request.scheme, request.host)
+    if app.config["URL_PREFIX"]:
+        url = url + "/" + app.config["URL_PREFIX"]
+    if app.config["API_VERSION"]:
+        url = url + "/" + app.config["API_VERSION"]
+    return [{"url": url}]
+
+
+def responses():
+    return {
+        "error": {
+            "description": "An error message",
+            "content": {
+                "application/json": {"schema": {"$ref": "#/components/schemas/Error"}}
+            },
+        }
+    }
+
+
+def parameters():
+    parameters = OrderedDict()
+    # resource parameters
+    for resource_name, rd in app.config["DOMAIN"].items():
+        if resource_name.endswith("_versions") or rd.get("disable_documentation"):
+            continue
+
+        title = rd["item_title"]
+        lookup_field = rd["item_lookup_field"]
+        if lookup_field not in rd["schema"]:
+            rd["schema"][lookup_field] = {"type": "objectid"}
+        eve_type = rd["schema"][lookup_field]["type"]
+        descr = rd["schema"][lookup_field].get("description") or ""
+        example = rd["schema"][lookup_field].get("example") or ""
+        if "data_relation" in rd["schema"][lookup_field]:
+            # the lookup field is a copy of another field
+            dr = rd["schema"][lookup_field]["data_relation"]
+
+            # resource definition of the data relation source
+            source_rd = app.config["DOMAIN"][dr["resource"]]
+
+            # schema of the data relation source field
+            source_def = source_rd["schema"][dr["field"]]
+
+            # key in #/definitions/...
+            source_def_name = source_rd["item_title"] + "_" + dr["field"]
+
+            # copy description if necessary
+            descr = descr or source_def.get("description")
+            descr = descr + " (links to {})".format(source_def_name)
+
+        p = OrderedDict()
+        p["in"] = "path"
+        p["name"] = title.lower() + "Id"
+        p["required"] = True
+        p["description"] = descr
+        if "SWAGGER_EXAMPLE_FIELD_REMOVE" not in app.config:
+            p["example"] = example
+        ptype = ""
+        if eve_type == "objectid" or eve_type == "datetime":
+            ptype = "string"
+        elif eve_type == "float":
+            ptype = "number"
+        else:
+            # TODO define default
+            pass
+
+        p["schema"] = {"type": ptype}
+        parameters[title + "_" + lookup_field] = p
+
+        # additional_lookup
+        if "additional_lookup" in rd:
+            lookup_field = rd["additional_lookup"]["field"]
+            descr = rd["schema"][lookup_field].get("description") or ""
+            example = rd["schema"][lookup_field].get("example") or ""
+
+            p = OrderedDict()
+            p["in"] = "path"
+            p["name"] = rd["additional_lookup"]["field"].title()
+            p["required"] = True
+            p["description"] = descr
+            p["example"] = example
+            p["schema"] = {"type": "string"}
+
+            parameters[title + "_" + lookup_field] = p
+
+    # add header parameters
+    parameters.update(_header_parameters())
+    # add query parameters
+    parameters.update(_query_parameters())
+    return parameters
+
+
+def _query_parameters():
+    params = {}
+
+    r = OrderedDict()
+    r["in"] = "query"
+    r["name"] = app.config["QUERY_WHERE"]
+    r["description"] = 'the filters query parameter (ex.: {"number": 10})'
+    r["schema"] = {"type": "string"}
+    params["query__where"] = r
+
+    r = OrderedDict()
+    r["in"] = "query"
+    r["name"] = app.config["QUERY_PROJECTION"]
+    r["description"] = 'the projections query parameter (ex.: {"name": 1})'
+    r["schema"] = {"type": "string"}
+    params["query__projections"] = r
+
+    r = OrderedDict()
+    r["in"] = "query"
+    r["name"] = app.config["QUERY_SORT"]
+    r["description"] = 'the sort query parameter (ex.: "city,-lastname")'
+    r["schema"] = {"type": "string"}
+    params["query__sort"] = r
+
+    r = OrderedDict()
+    r["in"] = "query"
+    r["name"] = app.config["QUERY_PAGE"]
+    r["description"] = "the pages query parameter"
+    r["schema"] = {"type": "integer", "example": 1}
+    params["query__page"] = r
+
+    r = OrderedDict()
+    r["in"] = "query"
+    r["name"] = app.config["QUERY_MAX_RESULTS"]
+    r["description"] = "the max results query parameter"
+    r["schema"] = {"type": "integer", "example": 25}
+    params["query__max_results"] = r
+
+    return params
+
+
+def _header_parameters():
+    r = OrderedDict()
+    r["in"] = "header"
+    r["name"] = "If-Match"
+    r["description"] = "Current value of the _etag field"
+    r["required"] = app.config["IF_MATCH"] and app.config["ENFORCE_IF_MATCH"]
+    r["schema"] = {"type": "string"}
+    return {"If-Match": r}
+
+
+def examples():
+    examples = OrderedDict()
+
+    for resource_name, rd in app.config["DOMAIN"].items():
+        if resource_name.endswith("_versions") or rd.get("disable_documentation"):
+            continue
+
+        title = rd["item_title"]
+        ex = OrderedDict()
+        ex["summary"] = "An example {0} document."
+        ex["description"] = (
+            "An example for {0} documents request bodies."
+            " Used in POST, PUT, PATCH methods."
+        ).format(title)
+        if "example" in rd:
+            ex["value"] = rd["example"]
+
+        examples[title] = ex
+
+    return examples
+
+
+def request_bodies():
+    def _get_ref_examples(rd):
+        return {"$ref": "#/components/examples/%s" % rd["item_title"]}
+
+    rbodies = OrderedDict()
+
+    for resource_name, rd in app.config["DOMAIN"].items():
+        if resource_name.endswith("_versions") or rd.get("disable_documentation"):
+            continue
+
+        title = rd["item_title"]
+        rb = OrderedDict()
+        description = "A {} document.".format(title)
+        if rd["bulk_enabled"]:
+            description = "A {0} or list of {0} documents".format(title)
+
+        rb["description"] = description
+        rb["required"] = True
+        rb["content"] = {
+            # TODO what about other methods
+            "application/json": {
+                "schema": get_ref_schema(rd),
+                "examples": {title: _get_ref_examples(rd)},
+            }
+        }
+        rbodies[title] = rb
+
+    return rbodies
+
+
+def headers():
+    pass
+
+
+def security_schemes():
+    if "flask_oauthlib.provider" in sys.modules.keys():
+        url = app.config.get(HOST) or request.host
+        return {
+            "oAuth2": {
+                "type": "oauth2",
+                "description": "oAuth2 password credentials.",
+                "flows": {
+                    "password": {
+                        # TODO why does this not work with a relative path?
+                        "tokenUrl": url
+                        + app.config["SENTINEL_ROUTE_PREFIX"]
+                        + app.config["SENTINEL_TOKEN_URL"],
+                        "scopes": {},
+                    }
+                },
+            }
+        }
+    if "eve_auth_jwt" in sys.modules.keys():
+        return {
+            "BearerAuth": {
+                "type": "http",
+                "scheme": "bearer",
+                "bearerFormat": "JWT",
+                "description": "Bearer authentication scheme.",
+            }
+        }
+    elif isinstance(app.auth, TokenAuth):
+        return {"BearerAuth": {"type": "http", "scheme": "bearer"}}
+    elif isinstance(app.auth, BasicAuth):
+        return {"BasicAuth": {"type": "http", "scheme": "basic"}}
+    else:
+        pass  # FIXME
+        # TODO use app.auth to build the security scheme
+        #      can not auto generate oauth, maybe should use add_documentation({...})
+
+
+def links():
+    pass
+
+
+def callbacks():
+    pass
+
+
+def security():
+    if "flask_oauthlib.provider" in sys.modules.keys():
+        return [{"oAuth2": []}]
+    elif "eve_auth_jwt" in sys.modules.keys():
+        return [{"BearerAuth": []}]
+    elif isinstance(app.auth, TokenAuth):
+        return [{"BearerAuth": []}]
+    elif isinstance(app.auth, BasicAuth):
+        return [{"BasicAuth": []}]
+
+
+def tags():
+    tags = []
+    for resource_name, rd in app.config["DOMAIN"].items():
+        if resource_name.endswith("_versions") or rd.get("disable_documentation"):
+            continue
+
+        tagInfo = {"name": rd["item_title"]}
+
+        if "description" in rd:
+            tagInfo["description"] = rd["description"]
+
+        tags.append(tagInfo)
+    return tags
+
+
+def external_docs():
+    pass