add specification experimental validator. (#29)

* add specification experimental validator.

Author: flask-pro

CHANGES.md

@@ -1,3 +1,7 @@
+## Version 0.15.0
+
+* Add specification experimental validator for OpenAPI 3.1.
+
 ## Version 0.14.6
 
 * The `default` response is now processed correctly.

README.md

@@ -41,7 +41,7 @@ Simple example
 OpenAPI 3 specification file `openapi.yaml`:
 
 ```yaml
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: Simple API for Flask-First
   version: 1.0.0

pyproject.toml

@@ -14,6 +14,7 @@ classifiers = [
 ]
 dependencies = [
   'Flask>=2.0.2',
+  'PyYAML>=6.0.1',
   'openapi-spec-validator>=0.5.0',
   'marshmallow>=3.14.1'
 ]
@@ -22,7 +23,7 @@ license = {file = "LICENSE"}
 name = "Flask-First"
 readme = "README.md"
 requires-python = ">=3.9"
-version = "0.14.6"
+version = "0.15.0"
 
 [project.optional-dependencies]
 dev = [

src/flask_first/__init__.py

@@ -34,12 +34,11 @@ def __init__(
         self.app = app
         self.path_to_spec = path_to_spec
         self.swagger_ui_path = swagger_ui_path
+        self.spec = None
 
         if self.app is not None:
             self.init_app(app)
 
-        self.spec = Specification(path_to_spec)
-
         self._mapped_routes_from_spec = []
 
     @staticmethod
@@ -51,12 +50,15 @@ def _route_registration_in_flask(self, func: callable) -> None:
 
         for path, path_item in self.spec.resolved_spec['paths'].items():
             for method_name, operation in path_item.items():
-                if operation.get('operationId') == func.__name__:
+                route_from_spec = operation.get('operationId')
+                if route_from_spec == func.__name__:
                     route: str = path
                     method: str = method_name
 
         if not route:
-            raise FirstException(f'Route function <{route}> not found in OpenAPI specification!')
+            raise FirstException(
+                f'Route function <{func.__name__}> not found in OpenAPI specification!'
+            )
 
         params_schema = self.spec.resolved_spec['paths'][route][method].get('parameters')
 
@@ -243,8 +245,14 @@ def add_response_validating(response: Response) -> Response:
     def init_app(self, app: Flask) -> None:
         self.app = app
         self.app.config.setdefault('FIRST_RESPONSE_VALIDATION', False)
+        self.app.config.setdefault('FIRST_EXPERIMENTAL_VALIDATOR', False)
         self.app.extensions['first'] = self
 
+        self.spec = Specification(
+            self.path_to_spec,
+            experimental_validator=self.app.config['FIRST_EXPERIMENTAL_VALIDATOR'],
+        )
+
         if self.swagger_ui_path:
             add_swagger_ui_blueprint(self.app, self.path_to_spec, self.swagger_ui_path)
 

src/flask_first/first/specification.py

@@ -8,19 +8,29 @@
 
 from ..schema.schema_maker import make_marshmallow_schema
 from .exceptions import FirstOpenAPIValidation
+from .validator import OpenAPI310ValidationError
+from .validator import Validator
 
 
 class Specification:
-    def __init__(self, path: Path):
-        self.raw_spec, _ = read_from_filename(path)
-        self._validating_openapi_file()
+    def __init__(self, path: [Path | str], experimental_validator: bool = False):
+        self.path = path
+        self.experimental_validator = experimental_validator
+        self.raw_spec, _ = read_from_filename(self.path)
+        self._validating_openapi_file(self.path, self.experimental_validator)
         self.resolved_spec = self._resolving_refs()
         self.serialized_spec = self._convert_schemas(self.resolved_spec)
 
-    def _validating_openapi_file(self):
+    def _validating_openapi_file(self, path: Path, experimental_validator: bool):
+        if experimental_validator:
+            try:
+                Validator(path).validate()
+            except OpenAPI310ValidationError as e:
+                raise FirstOpenAPIValidation(repr(e))
+
         try:
             validate(self.raw_spec)
-        except OpenAPIValidationError as e:
+        except (OpenAPIValidationError, TypeError) as e:
             raise FirstOpenAPIValidation(repr(e))
 
     def _resolving_all_refs(self, schema: dict) -> dict or list:

src/flask_first/first/validator.py

@@ -0,0 +1,90 @@
+from pathlib import Path
+
+import yaml
+from marshmallow import fields
+from marshmallow import pre_load
+from marshmallow import Schema
+from marshmallow import validate
+from marshmallow import ValidationError
+
+OPENAPI_VERSION = '3.1.0'
+TYPES = ['array', 'boolean', 'integer', 'number', 'object', 'string']
+RE_VERSION = r'^[0-9]+.[0-9]+.[0-9]+$'
+
+ENDPOINT_FIELD = fields.String(required=True, validate=validate.Regexp(r'^[/][0-9a-z-{}/]*[^/]$'))
+HTTP_CODE_FIELD = fields.String(required=True, validate=validate.Regexp(r'^[1-5]{1}\d{2}|default$'))
+DESCRIPTION_FIELD = fields.String(required=True)
+MEDIA_TYPE_FIELD = fields.String(required=True)
+
+
+class OpenAPI310ValidationError(Exception):
+    """OpenAPI specification validation error."""
+
+
+class InfoSchema(Schema):
+    title = fields.String(required=True)
+    version = fields.String(required=True, validate=validate.Regexp(RE_VERSION))
+
+
+class SchemaObjectSchema(Schema):
+    type = fields.String(required=True, validate=validate.OneOf(TYPES))
+    properties = fields.Dict(
+        keys=fields.String(required=True), values=fields.Nested('SchemaObjectSchema')
+    )
+
+
+class MediaTypeObjectSchema(Schema):
+    schema = fields.Nested(SchemaObjectSchema)
+
+
+class ResponsesObjectSchema(Schema):
+    description = DESCRIPTION_FIELD
+    content = fields.Dict(keys=MEDIA_TYPE_FIELD, values=fields.Nested(MediaTypeObjectSchema))
+
+
+class OperationObjectSchema(Schema):
+    operation_id = fields.String(data_key='operationId')
+    responses = fields.Dict(keys=HTTP_CODE_FIELD, values=fields.Nested(ResponsesObjectSchema))
+
+    @pre_load
+    def normalize_nested_keys(self, data, **kwargs):
+        responses_with_key_as_str = {str(k): v for k, v in data['responses'].items()}
+        data['responses'] = responses_with_key_as_str
+        return data
+
+
+class PathItemObjectSchema(Schema):
+    get = fields.Nested(OperationObjectSchema)
+
+
+class RootSchema(Schema):
+    openapi = fields.String(
+        required=True,
+        validate=validate.And(
+            validate.Equal(OPENAPI_VERSION), validate.Regexp(r'^[/][0-9a-z-{}/]*[^/]$')
+        ),
+    )
+    info = fields.Nested(InfoSchema, required=True)
+    paths = fields.Dict(
+        required=True,
+        keys=ENDPOINT_FIELD,
+        values=fields.Nested(PathItemObjectSchema, required=True),
+    )
+
+
+class Validator:
+    def __init__(self, path: Path | str):
+        self.path = path
+        self.raw_spec = self._yaml_to_dict(self.path)
+
+    @staticmethod
+    def _yaml_to_dict(path: Path) -> dict:
+        with open(path) as f:
+            s = yaml.safe_load(f)
+        return s
+
+    def validate(self) -> None or OpenAPI310ValidationError:
+        try:
+            RootSchema().validate(self.raw_spec)
+        except ValidationError as e:
+            raise OpenAPI310ValidationError(e)

tests/conftest.py

@@ -12,7 +12,7 @@
 @pytest.fixture()
 def fx_config():
     class Config:
-        PATH_TO_SPEC = Path(BASEDIR, 'specs/v3.0/openapi.yaml')
+        PATH_TO_SPEC = Path(BASEDIR, 'specs/v3.1.0/openapi.yaml')
 
     return Config
 

tests/specs/bad.openapi.yaml

@@ -1,3 +1,3 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: Bad API for testing Flask-First

tests/specs/not_valid/empty.openapi.yaml

@@ -0,0 +1,4 @@
+openapi: 3.1.0
+info:
+  title: API for testing Flask-First
+  version: 1.0.0