Initial schemas validation support

Author: noirbizarre

CHANGELOG.rst

@@ -8,6 +8,7 @@ Current
 
 - Fix missing changelog inprevious release
 - Ensure definitions with both `$ref` and description (or other property) output is valid (using `allOf`)
+- Added initial specifications schemas and validation support
 
 0.12.0 (2018-09-27)
 -------------------

doc/api.rst

@@ -75,6 +75,13 @@ Errors
 .. autoexception:: flask_restplus.mask.ParseError
 
 
+Schemas
+-------
+
+.. automodule:: flask_restplus.schemas
+    :members:
+
+
 Internals
 ---------
 

flask_restplus/api.py

@@ -19,7 +19,7 @@
 from flask.helpers import _endpoint_from_view_func
 from flask.signals import got_request_exception
 
-from jsonschema import RefResolver
+from jsonschema import RefResolver, validate
 
 from werkzeug import cached_property
 from werkzeug.datastructures import Headers

flask_restplus/schemas/__init__.py

@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+'''
+This module give access to OpenAPI specifications schemas
+and allows to validate specs against them.
+
+.. versionadded:: 0.12.1
+'''
+from __future__ import unicode_literals
+
+import json
+import pkg_resources
+
+from collections import Mapping
+
+from jsonschema import Draft4Validator
+
+from flask_restplus import errors
+
+
+class SchemaValidationError(errors.ValidationError):
+    '''
+    Raised when specification is not valid
+
+    .. versionadded:: 0.12.1
+    '''
+    def __init__(self, msg, errors=None):
+        super(SchemaValidationError, self).__init__(msg)
+        self.errors = errors
+
+    def __str__(self):
+        msg = [self.msg]
+        for error in sorted(self.errors, key=lambda e: e.path):
+            path = '.'.join(error.path)
+            msg.append('- {}: {}'.format(path, error.message))
+            for suberror in sorted(error.context, key=lambda e: e.schema_path):
+                path = '.'.join(suberror.schema_path)
+                msg.append('  - {}: {}'.format(path, suberror.message))
+        return '\n'.join(msg)
+
+    __unicode__ = __str__
+
+
+class LazySchema(Mapping):
+    '''
+    A thin wrapper around schema file lazy loading the data on first access
+
+    :param filename str: The package relative json schema filename
+    :param validator: The jsonschema validator class version
+
+    .. versionadded:: 0.12.1
+    '''
+    def __init__(self, filename, validator=Draft4Validator):
+        super(LazySchema, self).__init__()
+        self.filename = filename
+        self._schema = None
+        self._validator = validator
+
+    def _load(self):
+        if not self._schema:
+            data = pkg_resources.resource_string(__name__, self.filename)
+            self._schema = json.loads(data)
+
+    def __getitem__(self, key):
+        self._load()
+        return self._schema.__getitem__(key)
+
+    def __iter__(self):
+        self._load()
+        return self._schema.__iter__()
+
+    def __len__(self):
+        self._load()
+        return self._schema.__len__()
+
+    @property
+    def validator(self):
+        '''The jsonschema validator to validate against'''
+        return self._validator(self)
+
+
+#: OpenAPI 2.0 specification schema
+OAS_20 = LazySchema('oas-2.0.json')
+
+#: Map supported OpenAPI versions to their JSON schema
+VERSIONS = {
+    '2.0': OAS_20,
+}
+
+
+def validate(data):
+    '''
+    Validate an OpenAPI specification.
+
+    Supported OpenAPI versions: 2.0
+
+    :param data dict: The specification to validate
+    :returns boolean: True if the specification is valid
+    :raises SchemaValidationError: when the specification is invalid
+    :raises flask_restplus.errors.SpecsError: when it's not possible to determinate
+                                              the schema to validate against
+
+    .. versionadded:: 0.12.1
+    '''
+    if 'swagger' not in data:
+        raise errors.SpecsError('Unable to determinate OpenAPI schema version')
+
+    version = data['swagger']
+    if version not in VERSIONS:
+        raise errors.SpecsError('Unknown OpenAPI schema version "{}"'.format(version))
+
+    validator = VERSIONS[version].validator
+
+    validation_errors = list(validator.iter_errors(data))
+    if validation_errors:
+        raise SchemaValidationError('OpenAPI {} validation failed'.format(version),
+                                    errors=validation_errors)
+    return True