flask-openapi 4.3.1__py3-none-any.whl

flask_openapi/__init__.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2021/4/30 10:14
+
+from .__version__ import __version__
+from .blueprint import APIBlueprint
+from .models import (
+    XML,
+    APISpec,
+    Components,
+    Contact,
+    Discriminator,
+    Encoding,
+    Example,
+    ExternalDocumentation,
+    FileStorage,
+    Header,
+    Info,
+    License,
+    Link,
+    MediaType,
+    OAuthConfig,
+    OAuthFlow,
+    OAuthFlows,
+    Operation,
+    Parameter,
+    ParameterInType,
+    PathItem,
+    RawModel,
+    Reference,
+    RequestBody,
+    Response,
+    Schema,
+    SecurityScheme,
+    Server,
+    ServerVariable,
+    StyleValues,
+    Tag,
+    UnprocessableEntity,
+    ValidationErrorModel,
+)
+from .openapi import OpenAPI
+from .request import validate_request
+from .view import APIView

flask_openapi/__version__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2022/4/30 9:20
+
+__version__ = "4.3.1"

flask_openapi/blueprint.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2022/4/1 16:54
+import inspect
+from typing import Any, Callable
+
+from flask import Blueprint
+
+from .models import ExternalDocumentation, Server, Tag
+from .scaffold import APIScaffold
+from .types import ParametersTuple, ResponseDict
+from .utils import (
+    HTTPMethod,
+    convert_responses_key_to_string,
+    get_operation,
+    get_operation_id_for_path,
+    get_responses,
+    parse_and_store_tags,
+    parse_method,
+    parse_parameters,
+    parse_rule,
+)
+
+
+class APIBlueprint(APIScaffold, Blueprint):
+    def __init__(
+        self,
+        name: str,
+        import_name: str,
+        *,
+        abp_tags: list[Tag] | None = None,
+        abp_security: list[dict[str, list[str]]] | None = None,
+        abp_responses: ResponseDict | None = None,
+        doc_ui: bool = True,
+        operation_id_callback: Callable = get_operation_id_for_path,
+        validate_response: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Based on Flask Blueprint
+
+        Args:
+            name: The name of the blueprint. It Will be prepared to each endpoint name.
+            import_name: The name of the blueprint package, usually ``__name__``.
+                         This helps locate the ``root_path`` for the blueprint.
+            abp_tags: APIBlueprint tags for every API.
+            abp_security: APIBlueprint security for every API.
+            abp_responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
+            doc_ui: Enable OpenAPI document UI (Swagger UI, Redoc, and Rapidoc). Defaults to True.
+            operation_id_callback: Callback function for custom operation_id generation.
+                                   Receives name (str), path (str) and method (str) parameters.
+                                   Defaults to `get_operation_id_for_path` from utils
+            validate_response: Verify the response body.
+            **kwargs: Flask Blueprint kwargs
+        """
+        super(APIBlueprint, self).__init__(name, import_name, **kwargs)
+
+        # Initialize instance variables
+        self.paths: dict = dict()
+        self.components_schemas: dict = dict()
+        self.tags: list[Tag] = []
+        self.tag_names: list[str] = []
+
+        # Set values from arguments or default values
+        self.abp_tags = abp_tags or []
+        self.abp_security = abp_security or []
+
+        # Convert key to string
+        self.abp_responses = convert_responses_key_to_string(abp_responses or {})
+
+        self.doc_ui = doc_ui
+
+        # Set the operation ID callback function
+        self.operation_id_callback: Callable = operation_id_callback
+
+        # Verify the response body
+        self.validate_response = validate_response
+
+    def register_api(self, api: "APIBlueprint") -> None:
+        """Register a nested APIBlueprint"""
+
+        # Check if the APIBlueprint is being registered on itself
+        if api is self:
+            raise ValueError("Cannot register a api blueprint on itself")
+
+        # Merge tags from the nested APIBlueprint
+        for tag in api.tags:
+            if tag.name not in self.tag_names:
+                self.tags.append(tag)
+
+        # Merge paths from the nested APIBlueprint
+        for path_url, path_item in api.paths.items():
+            # Parse rule: merge url_prefix and format rule from /pet/<petId> to /pet/{petId}
+            uri = parse_rule(path_url, url_prefix=self.url_prefix)
+
+            self.paths[uri] = path_item
+
+        # Merge component schemas from the nested APIBlueprint
+        self.components_schemas.update(api.components_schemas)
+
+        # Register the nested APIBlueprint as a blueprint
+        self.register_blueprint(api)
+
+    def _add_url_rule(
+        self,
+        rule,
+        endpoint=None,
+        view_func=None,
+        provide_automatic_options=None,
+        **options,
+    ) -> None:
+        self.add_url_rule(rule, endpoint, view_func, provide_automatic_options, **options)
+
+    def _collect_openapi_info(
+        self,
+        rule: str,
+        func: Callable,
+        *,
+        tags: list[Tag] | None = None,
+        summary: str | None = None,
+        description: str | None = None,
+        external_docs: ExternalDocumentation | None = None,
+        operation_id: str | None = None,
+        responses: ResponseDict | None = None,
+        deprecated: bool | None = None,
+        security: list[dict[str, list[Any]]] | None = None,
+        servers: list[Server] | None = None,
+        openapi_extensions: dict[str, Any] | None = None,
+        doc_ui: bool = True,
+        method: str = HTTPMethod.GET,
+    ) -> ParametersTuple:
+        """
+        Collects OpenAPI specification information for Flask routes and view functions.
+
+        Args:
+            rule: Flask route
+            func: Flask view_func
+            tags: Adds metadata to a single tag.
+            summary: A short summary of what the operation does.
+            description: A verbose explanation of the operation behavior.
+            external_docs: Additional external documentation for this operation.
+            operation_id: Unique string used to identify the operation.
+            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
+            deprecated: Declares this operation to be deprecated.
+            security: A declaration of which security mechanisms can be used for this operation.
+            servers: An alternative server array to service this operation.
+            openapi_extensions: Allows extensions to the OpenAPI Schema.
+            doc_ui: Declares this operation to be shown. Default to True.
+        """
+        if self.doc_ui is True and doc_ui is True:
+            # Convert key to string
+            new_responses = convert_responses_key_to_string(responses or {})
+
+            # Global response: combine API responses
+            combine_responses = {**self.abp_responses, **new_responses}
+
+            # Create operation
+            operation = get_operation(
+                func, summary=summary, description=description, openapi_extensions=openapi_extensions
+            )
+
+            # Set external docs
+            if external_docs:
+                operation.externalDocs = external_docs
+
+            # Unique string used to identify the operation.
+            operation_id_kwargs = {"name": func.__name__, "path": rule, "method": method}
+            if "bp_name" in list(inspect.signature(self.operation_id_callback).parameters.keys()):
+                operation_id_kwargs["bp_name"] = self.name
+            operation.operationId = operation_id or self.operation_id_callback(**operation_id_kwargs)
+
+            # Only set `deprecated` if True, otherwise leave it as None
+            if deprecated is not None:
+                operation.deprecated = deprecated
+
+            # Add security
+            _security = (security or []) + self.abp_security or None
+            if _security:
+                operation.security = _security
+
+            # Add servers
+            if servers:
+                operation.servers = servers
+
+            # Store tags
+            tags = (tags or []) + self.abp_tags
+            parse_and_store_tags(tags, self.tags, self.tag_names, operation)
+
+            # Parse response
+            get_responses(combine_responses, self.components_schemas, operation)
+
+            # Parse rule: merge url_prefix and format rule from /pet/<petId> to /pet/{petId}
+            uri = parse_rule(rule, url_prefix=self.url_prefix)
+
+            # Parse method
+            parse_method(uri, method, self.paths, operation)
+
+            # Parse parameters
+            return parse_parameters(func, components_schemas=self.components_schemas, operation=operation)
+        else:
+            return parse_parameters(func, doc_ui=False)

flask_openapi/commands.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2022/4/16 14:21
+import json
+
+from flask import current_app
+from flask.cli import click, with_appcontext
+
+
+@click.command(name="openapi")
+@click.option("--output", "-o", type=click.Path(), help="The output file path.")
+@click.option("--format", "-f", "_format", type=click.Choice(["json", "yaml"]), help="The output file format.")
+@click.option("--indent", "-i", type=int, help="The indentation for JSON dumps.")
+@with_appcontext
+def openapi_command(output, _format, indent):
+    """Export the OpenAPI Specification to console or a file"""
+
+    # Check if the current app has an api_doc attribute
+    if hasattr(current_app, "api_doc"):
+        obj = current_app.api_doc
+
+        # Generate the OpenAPI Specification based on the specified format
+        if _format == "yaml":
+            try:
+                import yaml  # type: ignore
+            except ImportError:  # pragma: no cover
+                raise ImportError("pyyaml must be installed.")
+            openapi = yaml.safe_dump(obj, allow_unicode=True)
+        else:
+            openapi = json.dumps(obj, indent=indent, ensure_ascii=False)
+
+        # Save the OpenAPI Specification to a file if the output path is provided
+        if output:
+            with open(output, "w", encoding="utf8") as f:
+                f.write(openapi)
+            click.echo(f"Saved to {output}.")
+        else:
+            click.echo(openapi)

flask_openapi/models/__init__.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2021/4/28 10:58
+"""
+OpenAPI v3.1.0 schema types, created according to the specification:
+https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
+
+The type orders are according to the contents of the specification:
+https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#table-of-contents
+"""
+
+from flask import Request
+from pydantic import BaseModel
+
+from .callback import Callback
+from .components import Components
+from .contact import Contact
+from .discriminator import Discriminator
+from .encoding import Encoding
+from .example import Example
+from .external_documentation import ExternalDocumentation
+from .file import FileStorage
+from .header import Header
+from .info import Info
+from .license import License
+from .link import Link
+from .media_type import MediaType
+from .oauth_flow import OAuthFlow
+from .oauth_flows import OAuthFlows
+from .operation import Operation
+from .parameter import Parameter
+from .parameter_in_type import ParameterInType
+from .path_item import PathItem
+from .paths import Paths
+from .reference import Reference
+from .request_body import RequestBody
+from .response import Response
+from .responses import Responses
+from .schema import Schema
+from .security_requirement import SecurityRequirement
+from .security_scheme import SecurityScheme
+from .server import Server
+from .server_variable import ServerVariable
+from .style_values import StyleValues
+from .tag import Tag
+from .validation_error import UnprocessableEntity, ValidationErrorModel
+from .xml import XML
+
+OPENAPI3_REF_PREFIX = "#/components/schemas"
+OPENAPI3_REF_TEMPLATE = OPENAPI3_REF_PREFIX + "/{model}"
+
+
+class APISpec(BaseModel):
+    """https://spec.openapis.org/oas/v3.1.0#openapi-object"""
+
+    openapi: str
+    info: Info
+    servers: list[Server] | None = None
+    paths: Paths
+    components: Components | None = None
+    security: list[SecurityRequirement] | None = None
+    tags: list[Tag] | None = None
+    externalDocs: ExternalDocumentation | None = None
+    webhooks: dict[str, PathItem | Reference] | None = None
+
+    model_config = {"extra": "allow"}
+
+
+class OAuthConfig(BaseModel):
+    """
+    https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md#oauth-20-configuration
+    """
+
+    clientId: str | None = None
+    clientSecret: str | None = None
+    realm: str | None = None
+    appName: str | None = None
+    scopeSeparator: str | None = None
+    scopes: str | None = None
+    additionalQueryStringParams: dict[str, str] | None = None
+    useBasicAuthenticationWithAccessCodeGrant: bool | None = False
+    usePkceWithAuthorizationCodeGrant: bool | None = False
+
+
+class RawModel(Request):
+    mimetypes: list[str] = ["application/json"]
+
+
+Encoding.model_rebuild()
+Operation.model_rebuild()
+PathItem.model_rebuild()

flask_openapi/models/callback.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:35
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .path_item import PathItem
+else:
+    PathItem = "PathItem"
+
+"""
+A map of possible out-of band callbacks related to the parent operation.
+Each value in the map is a [Path Item Object](#pathItemObject)
+that describes a set of requests that may be initiated by the API provider and the expected responses.
+The key value used to identify the path item object is an expression, evaluated at runtime,
+that identifies a URL to use for the callback operation.
+"""
+Callback = dict[str, PathItem]

flask_openapi/models/components.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:36
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .callback import Callback
+from .example import Example
+from .header import Header
+from .link import Link
+from .parameter import Parameter
+from .path_item import PathItem
+from .reference import Reference
+from .request_body import RequestBody
+from .response import Response
+from .schema import Schema
+from .security_scheme import SecurityScheme
+
+
+class Components(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#components-object
+    """
+
+    schemas: dict[str, Reference | Schema] | None = Field(None)
+    responses: dict[str, Response | Reference] | None = None
+    parameters: dict[str, Parameter | Reference] | None = None
+    examples: dict[str, Example | Reference] | None = None
+    requestBodies: dict[str, RequestBody | Reference] | None = None
+    headers: dict[str, Header | Reference] | None = None
+    securitySchemes: dict[str, SecurityScheme | dict[str, Any]] | None = None
+    links: dict[str, Link | Reference] | None = None
+    callbacks: dict[str, Callback | Reference] | None = None
+    pathItems: dict[str, PathItem | Reference] | None = None
+
+    model_config = {"extra": "allow"}

flask_openapi/models/contact.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:37
+
+from pydantic import BaseModel
+
+
+class Contact(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#contact-object
+    """
+
+    name: str | None = None
+    url: str | None = None
+    email: str | None = None
+
+    model_config = {"extra": "allow"}

flask_openapi/models/data_type.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:38
+from enum import Enum
+
+
+class DataType(str, Enum):
+    """
+    https://spec.openapis.org/oas/v3.1.0#data-types
+    """
+
+    STRING = "string"
+    NUMBER = "number"
+    INTEGER = "integer"
+    BOOLEAN = "boolean"
+    ARRAY = "array"
+    OBJECT = "object"
+    NUll = "null"

flask_openapi/models/discriminator.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:41
+
+from pydantic import BaseModel
+
+
+class Discriminator(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#discriminator-object
+    """
+
+    propertyName: str
+    mapping: dict[str, str] | None = None
+
+    model_config = {"extra": "allow"}

flask_openapi/models/encoding.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:41
+from typing import TYPE_CHECKING, Union
+
+from pydantic import BaseModel
+
+from .reference import Reference
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .header import Header
+else:
+    Header = "Header"
+
+
+class Encoding(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#encoding-object
+    """
+
+    contentType: str | None = None
+    headers: dict[str, Union[Header, Reference]] | None = None
+    style: str | None = None
+    explode: bool | None = None
+    allowReserved: bool = False
+
+    model_config = {"extra": "allow"}

flask_openapi/models/example.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:42
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class Example(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#example-object
+    """
+
+    summary: str | None = None
+    description: str | None = None
+    value: Any | None = None
+    externalValue: str | None = None
+
+    model_config = {"extra": "allow"}

flask_openapi/models/external_documentation.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:43
+
+from pydantic import BaseModel
+
+
+class ExternalDocumentation(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#external-documentation-object
+    """
+
+    description: str | None = None
+    url: str
+
+    model_config = {"extra": "allow"}

flask_openapi/models/file.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2021/5/11 16:17
+from typing import Any
+
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import core_schema
+from werkzeug.datastructures import FileStorage as _FileStorage
+
+
+class FileStorage(_FileStorage):
+    """
+    An uploaded file included as part of the request data.
+    """
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, *_args: Any, **_kwargs: Any) -> JsonSchemaValue:
+        field_schema = {"format": "binary", "type": "string"}
+        return field_schema
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, *_args: Any, **_kwargs: Any) -> core_schema.CoreSchema:
+        return core_schema.with_info_plain_validator_function(cls.validate)
+
+    @classmethod
+    def validate(cls, value: _FileStorage, *_args: Any, **_kwargs: Any) -> _FileStorage:
+        return value

flask_openapi/models/header.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:44
+
+from .parameter import Parameter
+from .parameter_in_type import ParameterInType
+
+
+class Header(Parameter):
+    """
+    https://spec.openapis.org/oas/v3.1.0#header-object
+    """
+
+    name: str | None = None  # type:ignore
+    param_in: ParameterInType | None = None  # type:ignore
+
+    model_config = {"extra": "allow"}

flask_openapi/models/info.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2021/4/28 10:58
+
+from pydantic import BaseModel
+
+from .contact import Contact
+from .license import License
+
+
+class Info(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#info-object
+    """
+
+    title: str
+    summary: str | None = None
+    description: str | None = None
+    termsOfService: str | None = None
+    contact: Contact | None = None
+    license: License | None = None
+    version: str
+
+    model_config = {"extra": "allow"}

flask_openapi/models/license.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:45
+
+from pydantic import BaseModel
+
+
+class License(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#license-object
+    """
+
+    name: str
+    identifier: str | None = None
+    url: str | None = None
+
+    model_config = {"extra": "allow"}

flask_openapi/models/link.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/4 9:45
+from typing import Any
+
+from pydantic import BaseModel
+
+from .server import Server
+
+
+class Link(BaseModel):
+    """
+    https://spec.openapis.org/oas/v3.1.0#link-object
+    """
+
+    operationRef: str | None = None
+    operationId: str | None = None
+    parameters: dict[str, Any] | None = None
+    requestBody: Any | None = None
+    description: str | None = None
+    server: Server | None = None
+
+    model_config = {"extra": "allow"}