flask-openapi 4.3.1__py3-none-any.whl

flask_openapi/scaffold.py

@@ -0,0 +1,547 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2022/8/30 9:40
+import inspect
+from functools import wraps
+from typing import Any, Callable
+
+from flask import current_app
+from flask.wrappers import Response as FlaskResponse
+
+from .models import ExternalDocumentation, Server, Tag
+from .request import _validate_request
+from .types import ParametersTuple, ResponseDict
+from .utils import HTTPMethod
+
+
+class APIScaffold:
+    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:
+        raise NotImplementedError  # pragma: no cover
+
+    def register_api(self, api) -> None:
+        raise NotImplementedError  # pragma: no cover
+
+    def _add_url_rule(
+        self,
+        rule,
+        endpoint=None,
+        view_func=None,
+        provide_automatic_options=None,
+        **options,
+    ) -> None:
+        raise NotImplementedError  # pragma: no cover
+
+    @staticmethod
+    def create_view_func(
+        func,
+        header,
+        cookie,
+        path,
+        query,
+        form,
+        body,
+        raw,
+        view_class=None,
+        view_kwargs=None,
+        responses: ResponseDict | None = None,
+        validate_response: bool | None = None,
+    ):
+        is_coroutine_function = inspect.iscoroutinefunction(func)
+        if is_coroutine_function:
+
+            @wraps(func)
+            async def view_func(**kwargs) -> FlaskResponse:
+                if hasattr(func, "__delay_validate_request__") and func.__delay_validate_request__ is True:
+                    func_kwargs = kwargs
+                else:
+                    func_kwargs = _validate_request(
+                        header=header,
+                        cookie=cookie,
+                        path=path,
+                        query=query,
+                        form=form,
+                        body=body,
+                        raw=raw,
+                        path_kwargs=kwargs,
+                    )
+
+                # handle async request
+                if view_class:
+                    signature = inspect.signature(view_class.__init__)
+                    parameters = signature.parameters
+                    if parameters.get("view_kwargs"):
+                        view_object = view_class(view_kwargs=view_kwargs)
+                    else:
+                        view_object = view_class()
+                    response = await func(view_object, **func_kwargs)
+                else:
+                    response = await func(**func_kwargs)
+
+                if hasattr(current_app, "validate_response"):
+                    if validate_response is None:
+                        _validate_response = current_app.validate_response
+                    else:
+                        _validate_response = validate_response
+                else:
+                    _validate_response = validate_response
+
+                if _validate_response and responses:
+                    validate_response_callback = getattr(current_app, "validate_response_callback")
+                    return validate_response_callback(response, responses)
+
+                return response
+        else:
+
+            @wraps(func)
+            def view_func(**kwargs) -> FlaskResponse:
+                if hasattr(func, "__delay_validate_request__") and func.__delay_validate_request__ is True:
+                    func_kwargs = kwargs
+                else:
+                    func_kwargs = _validate_request(
+                        header=header,
+                        cookie=cookie,
+                        path=path,
+                        query=query,
+                        form=form,
+                        body=body,
+                        raw=raw,
+                        path_kwargs=kwargs,
+                    )
+
+                # handle request
+                if view_class:
+                    signature = inspect.signature(view_class.__init__)
+                    parameters = signature.parameters
+                    if parameters.get("view_kwargs"):
+                        view_object = view_class(view_kwargs=view_kwargs)
+                    else:
+                        view_object = view_class()
+                    response = func(view_object, **func_kwargs)
+                else:
+                    response = func(**func_kwargs)
+
+                if hasattr(current_app, "validate_response"):
+                    if validate_response is None:
+                        _validate_response = current_app.validate_response
+                    else:
+                        _validate_response = validate_response
+                else:
+                    _validate_response = validate_response
+
+                if _validate_response and responses:
+                    validate_response_callback = getattr(current_app, "validate_response_callback")
+                    return validate_response_callback(response, responses)
+
+                return response
+
+        if not hasattr(func, "view"):
+            func.view = view_func
+
+        return func.view
+
+    def get(
+        self,
+        rule: str,
+        *,
+        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,
+        validate_response: bool | None = None,
+        doc_ui: bool = True,
+        **options: Any,
+    ) -> Callable:
+        """
+        Decorator for defining a REST API endpoint with the HTTP GET method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            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.
+            validate_response: Verify the response body.
+        """
+
+        def decorator(func) -> Callable:
+            header, cookie, path, query, form, body, raw = self._collect_openapi_info(
+                rule,
+                func,
+                tags=tags,
+                summary=summary,
+                description=description,
+                external_docs=external_docs,
+                operation_id=operation_id,
+                responses=responses,
+                deprecated=deprecated,
+                security=security,
+                servers=servers,
+                openapi_extensions=openapi_extensions,
+                doc_ui=doc_ui,
+                method=HTTPMethod.GET,
+            )
+
+            _validate_response = validate_response if validate_response is not None else self.get_validate_response()
+            view_func = self.create_view_func(
+                func,
+                header,
+                cookie,
+                path,
+                query,
+                form,
+                body,
+                raw,
+                responses=responses,
+                validate_response=_validate_response,
+            )
+
+            options.update({"methods": [HTTPMethod.GET]})
+            self._add_url_rule(rule, view_func=view_func, **options)
+
+            return func
+
+        return decorator
+
+    def post(
+        self,
+        rule: str,
+        *,
+        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,
+        validate_response: bool | None = None,
+        doc_ui: bool = True,
+        **options: Any,
+    ) -> Callable:
+        """
+        Decorator for defining a REST API endpoint with the HTTP POST method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            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.
+            validate_response: Verify the response body.
+        """
+
+        def decorator(func) -> Callable:
+            header, cookie, path, query, form, body, raw = self._collect_openapi_info(
+                rule,
+                func,
+                tags=tags,
+                summary=summary,
+                description=description,
+                external_docs=external_docs,
+                operation_id=operation_id,
+                responses=responses,
+                deprecated=deprecated,
+                security=security,
+                servers=servers,
+                openapi_extensions=openapi_extensions,
+                doc_ui=doc_ui,
+                method=HTTPMethod.POST,
+            )
+
+            _validate_response = validate_response if validate_response is not None else self.get_validate_response()
+            view_func = self.create_view_func(
+                func,
+                header,
+                cookie,
+                path,
+                query,
+                form,
+                body,
+                raw,
+                responses=responses,
+                validate_response=_validate_response,
+            )
+
+            options.update({"methods": [HTTPMethod.POST]})
+            self._add_url_rule(rule, view_func=view_func, **options)
+
+            return func
+
+        return decorator
+
+    def put(
+        self,
+        rule: str,
+        *,
+        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,
+        validate_response: bool | None = None,
+        doc_ui: bool = True,
+        **options: Any,
+    ) -> Callable:
+        """
+        Decorator for defining a REST API endpoint with the HTTP PUT method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            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.
+            validate_response: Verify the response body.
+        """
+
+        def decorator(func) -> Callable:
+            header, cookie, path, query, form, body, raw = self._collect_openapi_info(
+                rule,
+                func,
+                tags=tags,
+                summary=summary,
+                description=description,
+                external_docs=external_docs,
+                operation_id=operation_id,
+                responses=responses,
+                deprecated=deprecated,
+                security=security,
+                servers=servers,
+                openapi_extensions=openapi_extensions,
+                doc_ui=doc_ui,
+                method=HTTPMethod.PUT,
+            )
+
+            _validate_response = validate_response if validate_response is not None else self.get_validate_response()
+            view_func = self.create_view_func(
+                func,
+                header,
+                cookie,
+                path,
+                query,
+                form,
+                body,
+                raw,
+                responses=responses,
+                validate_response=_validate_response,
+            )
+
+            options.update({"methods": [HTTPMethod.PUT]})
+            self._add_url_rule(rule, view_func=view_func, **options)
+
+            return func
+
+        return decorator
+
+    def delete(
+        self,
+        rule: str,
+        *,
+        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,
+        validate_response: bool | None = None,
+        doc_ui: bool = True,
+        **options: Any,
+    ) -> Callable:
+        """
+        Decorator for defining a REST API endpoint with the HTTP DELETE method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            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.
+            validate_response: Verify the response body.
+        """
+
+        def decorator(func) -> Callable:
+            header, cookie, path, query, form, body, raw = self._collect_openapi_info(
+                rule,
+                func,
+                tags=tags,
+                summary=summary,
+                description=description,
+                external_docs=external_docs,
+                operation_id=operation_id,
+                responses=responses,
+                deprecated=deprecated,
+                security=security,
+                servers=servers,
+                openapi_extensions=openapi_extensions,
+                doc_ui=doc_ui,
+                method=HTTPMethod.DELETE,
+            )
+
+            _validate_response = validate_response if validate_response is not None else self.get_validate_response()
+            view_func = self.create_view_func(
+                func,
+                header,
+                cookie,
+                path,
+                query,
+                form,
+                body,
+                raw,
+                responses=responses,
+                validate_response=_validate_response,
+            )
+
+            options.update({"methods": [HTTPMethod.DELETE]})
+            self._add_url_rule(rule, view_func=view_func, **options)
+
+            return func
+
+        return decorator
+
+    def patch(
+        self,
+        rule: str,
+        *,
+        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,
+        validate_response: bool | None = None,
+        doc_ui: bool = True,
+        **options: Any,
+    ) -> Callable:
+        """
+        Decorator for defining a REST API endpoint with the HTTP PATCH method.
+        More information goto https://spec.openapis.org/oas/v3.1.0#operation-object
+
+        Args:
+            rule: The URL rule string.
+            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.
+            validate_response: Verify the response body.
+        """
+
+        def decorator(func) -> Callable:
+            header, cookie, path, query, form, body, raw = self._collect_openapi_info(
+                rule,
+                func,
+                tags=tags,
+                summary=summary,
+                description=description,
+                external_docs=external_docs,
+                operation_id=operation_id,
+                responses=responses,
+                deprecated=deprecated,
+                security=security,
+                servers=servers,
+                openapi_extensions=openapi_extensions,
+                doc_ui=doc_ui,
+                method=HTTPMethod.PATCH,
+            )
+
+            _validate_response = validate_response if validate_response is not None else self.get_validate_response()
+            view_func = self.create_view_func(
+                func,
+                header,
+                cookie,
+                path,
+                query,
+                form,
+                body,
+                raw,
+                responses=responses,
+                validate_response=_validate_response,
+            )
+
+            options.update({"methods": [HTTPMethod.PATCH]})
+            self._add_url_rule(rule, view_func=view_func, **options)
+
+            return func
+
+        return decorator
+
+    def get_validate_response(self):
+        if hasattr(self, "validate_response"):
+            if self.validate_response is not None:
+                return self.validate_response

flask_openapi/templates.py

@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/2/16 9:46
+
+
+openapi_html_string = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>APIdoc</title>
+    <link rel="shortcut icon" href="
+data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAkBJREFUSEutlU9oE1EQxr/ZPdiDRBR6K
+KIepAhevFqwZqNByT+ziaQevEQRUQ8eBQ9iCyLkJFiKJ21FRLCY3SbZpSoxT4sWBQ/24MEe9OJdiURrd3dka9XUNtm31Xd8M/P9ZubNe48Qcg0W7F4sLPY5
+GxbmZyeHvgaFU5BDu13Tq8Mg5fLy3kciuv5N/TLaDSQNiOVr55hp7O+EiGiOPb4mzNTEWslKAfy2qA7PAtjZsWLChCinTqxKQKZFWs46A+BGkC+BJhtGcqj
+dT6qCWM6+z+BCEADAJ2GkNocCaMVGDz63AqfFF2Xg3VMjtSsU4IBuH/KIH0pkDxCuiHLqUiiApltFEMaDAMQ82jDT50MfclS3LhLhancA3RZGsriuMY1la4
+dZoenOAK4LIx3vZA+cokTCjrR6+D0BW1aLcNNljs+YmVfrBviBWt4aB2ONFpAQRjLWrX2BFSwBVr5BbXr/CNh/tNqveGoJ4FynLF3X2TNTyc6FbpGWt4+Bu
+QRgR9cJItwU5dSpUICobpWIcCFo9v/Y+e6i6559Xsk2u96DeOHxJsf5fg9AQl582ZPwUiXldP1BYkW7fh9yvFDZ7jhqjYGtRJgH00Zm3kaESAjYB8Xj40+m
+0i9+xQROUaeXlEC3mN07vhApFGGmAYD2Al6/x97JZ+aRR0s2mey0nOX/Bf6f8HOxFxNmRsjESgEG89N9KrtvAPSCvRFhZoZlxKUr8B2jujVGwEDT9fa9rmZ
+a/x3gCx7M2rvrU8m3suK+3w+AcssZ50vnfwAAAABJRU5ErkJggg==
+    ">
+    <style>
+        body {
+            background-color: #131417;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+        }
+
+        .grid {
+            display: grid;
+            grid-template-columns: repeat(6, 1fr);
+            grid-gap: 36px;
+        }
+
+        .box {
+            grid-column: span 2;
+            width: 300px;
+            height: 200px;
+            background: #2c303a;
+            border-radius: 30px;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            position: relative;
+            transform: scale(1);
+            transition: all .3s ease;
+        }
+
+        /* Dealing with 2 orphan items */
+
+        .box:last-child:nth-child(3n - 1) {
+            grid-column-end: -2;
+        }
+
+        .box:nth-last-child(2):nth-child(3n + 1) {
+            grid-column-end: 4;
+        }
+
+        /* Dealing with single orphan */
+
+        .box:last-child:nth-child(3n - 2) {
+            grid-column-end: 5;
+        }
+
+        .box:hover {
+            transform: scale(1.1);
+            box-shadow: 0 0 20px #333743f0;
+        }
+
+        .box a {
+            color: white;
+            font-size: 30px;
+            user-select: none;
+        }
+
+        .box img {
+            user-select: none;
+            height: 64px;
+            margin-bottom: 10px;
+        }
+
+    </style>
+
+</head>
+<body>
+<div class="grid">
+    {% for ui in ui_templates %}
+    <div class="box" onclick="window.location.href='{{ ui.name }}';return false">
+        <img height="64" src="{{ ui.name }}/images/{{ ui.name }}.svg">
+        <a>{{ ui.display_name }}</a>
+    </div>
+    {% else %}
+    <div style="color: white; grid-column: span 2; display: flex; flex-direction: column; grid-column-end: 5;">
+        <p>Please install at least one optional UI:</p>
+        <p style="font-family: Consolas; background-color: #404348; border-radius: 5px; padding: 5px; font-size: 12px">
+        $ pip install -U flask-openapi3[swagger,redoc,rapidoc,rapipdf,scalar,elements]
+        </p>
+        <p>More optional ui templates goto the document about
+        <a href="https://luolingchun.github.io/flask-openapi3/latest/Usage/UI_Templates/" style="color: #0969da">
+        UI_Templates.
+        </a>
+        </p>
+    </div>
+    {% endfor %}
+</div>
+
+</body>
+</html>
+"""

flask_openapi/types.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+# @Author  : llc
+# @Time    : 2023/7/9 15:25
+from http import HTTPStatus
+from typing import Any, Type
+
+from pydantic import BaseModel
+
+from .models import RawModel, SecurityScheme
+
+_ResponseDictValue = Type[BaseModel] | dict[Any, Any] | None
+
+ResponseDict = dict[str | int | HTTPStatus, _ResponseDictValue]
+
+ResponseStrKeyDict = dict[str, _ResponseDictValue]
+
+SecuritySchemesDict = dict[str, SecurityScheme | dict[str, Any]]
+
+ParametersTuple = tuple[
+    Type[BaseModel] | None,
+    Type[BaseModel] | None,
+    Type[BaseModel] | None,
+    Type[BaseModel] | None,
+    Type[BaseModel] | None,
+    Type[BaseModel] | None,
+    Type[RawModel] | None,
+]