APIView

APIView

Source code in flask_openapi3/view.py

class APIView:
    def __init__(
            self,
            url_prefix: Optional[str] = None,
            view_tags: Optional[List[Tag]] = None,
            view_security: Optional[List[Dict[str, List[str]]]] = None,
            view_responses: Optional[ResponseDict] = None,
            doc_ui: bool = True,
            operation_id_callback: Callable = get_operation_id_for_path,
    ):
        """
        Create a class-based view

        Arguments:
            url_prefix: A path to prepend to all the APIView's urls
            view_tags: APIView tags for every API.
            view_security: APIView security for every API.
            view_responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
            doc_ui: Enable OpenAPI document UI (Swagger UI and Redoc). 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
        """
        self.url_prefix = url_prefix
        self.view_tags = view_tags or []
        self.view_security = view_security or []

        view_responses = view_responses or {}
        # Convert key to string
        self.view_responses = convert_responses_key_to_string(view_responses)

        self.doc_ui = doc_ui
        self.operation_id_callback: Callable = operation_id_callback

        self.views: Dict = dict()
        self.paths: Dict = dict()
        self.components_schemas: Dict = dict()
        self.tags: List[Tag] = []
        self.tag_names: List[str] = []

    def route(self, rule: str):
        """Decorator for view class"""

        def wrapper(cls):
            if self.views.get(rule):
                raise ValueError(f"malformed url rule: {rule!r}")
            methods = []

            # Parse rule: merge url_prefix and format rule from /pet/<petId> to /pet/{petId}
            uri = parse_rule(rule, url_prefix=self.url_prefix)

            for method in HTTPMethod:
                cls_method = getattr(cls, method.lower(), None)
                if not cls_method:
                    continue
                methods.append(method)
                if self.doc_ui is False:
                    continue
                if not getattr(cls_method, "operation", None):
                    continue
                # Parse method
                parse_method(uri, method, self.paths, cls_method.operation)
                # Update operation_id
                if not cls_method.operation.operationId:
                    cls_method.operation.operationId = self.operation_id_callback(
                        name=cls_method.__qualname__,
                        path=rule,
                        method=method
                    )

            # Convert route parameters from {param} to <param>
            _rule = uri.replace("{", "<").replace("}", ">")
            self.views[_rule] = (cls, methods)

            return cls

        return wrapper

    def doc(
            self,
            *,
            tags: Optional[List[Tag]] = None,
            summary: Optional[str] = None,
            description: Optional[str] = None,
            external_docs: Optional[ExternalDocumentation] = None,
            operation_id: Optional[str] = None,
            extra_form: Optional[ExtraRequestBody] = None,
            extra_body: Optional[ExtraRequestBody] = None,
            responses: Optional[ResponseDict] = None,
            extra_responses: Optional[Dict[str, dict]] = None,
            deprecated: Optional[bool] = None,
            security: Optional[List[Dict[str, List[Any]]]] = None,
            servers: Optional[List[Server]] = None,
            openapi_extensions: Optional[Dict[str, Any]] = None,
            doc_ui: bool = True
    ) -> Callable:
        """
        Decorator for view method.
        More information goto https://spec.openapis.org/oas/v3.0.3#operation-object

        Arguments:
            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.
            extra_form: **Deprecated in v3.x**. Extra information describing the request body(application/form).
            extra_body: **Deprecated in v3.x**. Extra information describing the request body(application/json).
            responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
            extra_responses: **Deprecated in v3.x**. Extra information for responses.
            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 extra_form is not None:
            warnings.warn(
                """`extra_form` will be deprecated in v3.x, please use `openapi_extra` instead.""",
                DeprecationWarning)
        if extra_body is not None:
            warnings.warn(
                """`extra_body` will be deprecated in v3.x, please use `openapi_extra` instead.""",
                DeprecationWarning)
        if extra_responses is not None:
            warnings.warn(
                """`extra_responses` will be deprecated in v3.x, please use `responses` instead.""",
                DeprecationWarning)

        if responses is None:
            new_responses = {}
        else:
            # Convert key to string
            new_responses = convert_responses_key_to_string(responses)
        if extra_responses is None:
            extra_responses = {}
        if security is None:
            security = []
        tags = tags + self.view_tags if tags else self.view_tags

        def decorator(func):
            if self.doc_ui is False or doc_ui is False:
                return
            # Global response combines API responses
            combine_responses = deepcopy(self.view_responses)
            combine_responses.update(**new_responses)
            # Create operation
            operation = get_operation(
                func,
                summary=summary,
                description=description,
                openapi_extensions=openapi_extensions
            )
            # Set external docs
            operation.externalDocs = external_docs
            # Unique string used to identify the operation.
            operation.operationId = operation_id
            # Only set `deprecated` if True, otherwise leave it as None
            operation.deprecated = deprecated
            # Add security
            operation.security = security + self.view_security or None
            # Add servers
            operation.servers = servers
            # Store tags
            parse_and_store_tags(tags, self.tags, self.tag_names, operation)
            # Parse parameters
            parse_parameters(
                func,
                extra_form=extra_form,
                extra_body=extra_body,
                components_schemas=self.components_schemas,
                operation=operation
            )
            # Parse response
            get_responses(combine_responses, extra_responses, self.components_schemas, operation)
            func.operation = operation

            return func

        return decorator

    def register(self, app: "OpenAPI", view_kwargs: Optional[Dict[Any, Any]] = None):
        """
        Register the API views with the given OpenAPI app.

        Args:
            app: An instance of the OpenAPI app.
            view_kwargs: Additional keyword arguments to pass to the API views.
        """
        if view_kwargs is None:
            view_kwargs = {}
        for rule, (cls, methods) in self.views.items():
            for method in methods:
                func = getattr(cls, method.lower())
                header, cookie, path, query, form, body = parse_parameters(func, doc_ui=False)
                view_func = app.create_view_func(
                    func,
                    header,
                    cookie,
                    path,
                    query,
                    form,
                    body,
                    view_class=cls,
                    view_kwargs=view_kwargs
                )
                options = {
                    "endpoint": cls.__name__ + "." + method.lower(),
                    "methods": [method.upper()]
                }
                app.add_url_rule(rule, view_func=view_func, **options)

__init__(url_prefix=None, view_tags=None, view_security=None, view_responses=None, doc_ui=True, operation_id_callback=get_operation_id_for_path)

Create a class-based view

Parameters:

Name	Type	Description	Default
url_prefix	Optional[str]	A path to prepend to all the APIView's urls	None
view_tags	Optional[List[Tag]]	APIView tags for every API.	None
view_security	Optional[List[Dict[str, List[str]]]]	APIView security for every API.	None
view_responses	Optional[ResponseDict]	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
doc_ui	bool	Enable OpenAPI document UI (Swagger UI and Redoc). Defaults to True.	True
operation_id_callback	Callable	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	get_operation_id_for_path

Source code in flask_openapi3/view.py

def __init__(
        self,
        url_prefix: Optional[str] = None,
        view_tags: Optional[List[Tag]] = None,
        view_security: Optional[List[Dict[str, List[str]]]] = None,
        view_responses: Optional[ResponseDict] = None,
        doc_ui: bool = True,
        operation_id_callback: Callable = get_operation_id_for_path,
):
    """
    Create a class-based view

    Arguments:
        url_prefix: A path to prepend to all the APIView's urls
        view_tags: APIView tags for every API.
        view_security: APIView security for every API.
        view_responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
        doc_ui: Enable OpenAPI document UI (Swagger UI and Redoc). 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
    """
    self.url_prefix = url_prefix
    self.view_tags = view_tags or []
    self.view_security = view_security or []

    view_responses = view_responses or {}
    # Convert key to string
    self.view_responses = convert_responses_key_to_string(view_responses)

    self.doc_ui = doc_ui
    self.operation_id_callback: Callable = operation_id_callback

    self.views: Dict = dict()
    self.paths: Dict = dict()
    self.components_schemas: Dict = dict()
    self.tags: List[Tag] = []
    self.tag_names: List[str] = []

doc(*, tags=None, summary=None, description=None, external_docs=None, operation_id=None, extra_form=None, extra_body=None, responses=None, extra_responses=None, deprecated=None, security=None, servers=None, openapi_extensions=None, doc_ui=True)

Decorator for view method. More information goto https://spec.openapis.org/oas/v3.0.3#operation-object

Parameters:

Name	Type	Description	Default
tags	Optional[List[Tag]]	Adds metadata to a single tag.	None
summary	Optional[str]	A short summary of what the operation does.	None
description	Optional[str]	A verbose explanation of the operation behavior.	None
external_docs	Optional[ExternalDocumentation]	Additional external documentation for this operation.	None
operation_id	Optional[str]	Unique string used to identify the operation.	None
extra_form	Optional[ExtraRequestBody]	Deprecated in v3.x. Extra information describing the request body(application/form).	None
extra_body	Optional[ExtraRequestBody]	Deprecated in v3.x. Extra information describing the request body(application/json).	None
responses	Optional[ResponseDict]	API responses should be either a subclass of BaseModel, a dictionary, or None.	None
extra_responses	Optional[Dict[str, dict]]	Deprecated in v3.x. Extra information for responses.	None
deprecated	Optional[bool]	Declares this operation to be deprecated.	None
security	Optional[List[Dict[str, List[Any]]]]	A declaration of which security mechanisms can be used for this operation.	None
servers	Optional[List[Server]]	An alternative server array to service this operation.	None
openapi_extensions	Optional[Dict[str, Any]]	Allows extensions to the OpenAPI Schema.	None
doc_ui	bool	Declares this operation to be shown. Default to True.	True

Source code in flask_openapi3/view.py

def doc(
        self,
        *,
        tags: Optional[List[Tag]] = None,
        summary: Optional[str] = None,
        description: Optional[str] = None,
        external_docs: Optional[ExternalDocumentation] = None,
        operation_id: Optional[str] = None,
        extra_form: Optional[ExtraRequestBody] = None,
        extra_body: Optional[ExtraRequestBody] = None,
        responses: Optional[ResponseDict] = None,
        extra_responses: Optional[Dict[str, dict]] = None,
        deprecated: Optional[bool] = None,
        security: Optional[List[Dict[str, List[Any]]]] = None,
        servers: Optional[List[Server]] = None,
        openapi_extensions: Optional[Dict[str, Any]] = None,
        doc_ui: bool = True
) -> Callable:
    """
    Decorator for view method.
    More information goto https://spec.openapis.org/oas/v3.0.3#operation-object

    Arguments:
        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.
        extra_form: **Deprecated in v3.x**. Extra information describing the request body(application/form).
        extra_body: **Deprecated in v3.x**. Extra information describing the request body(application/json).
        responses: API responses should be either a subclass of BaseModel, a dictionary, or None.
        extra_responses: **Deprecated in v3.x**. Extra information for responses.
        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 extra_form is not None:
        warnings.warn(
            """`extra_form` will be deprecated in v3.x, please use `openapi_extra` instead.""",
            DeprecationWarning)
    if extra_body is not None:
        warnings.warn(
            """`extra_body` will be deprecated in v3.x, please use `openapi_extra` instead.""",
            DeprecationWarning)
    if extra_responses is not None:
        warnings.warn(
            """`extra_responses` will be deprecated in v3.x, please use `responses` instead.""",
            DeprecationWarning)

    if responses is None:
        new_responses = {}
    else:
        # Convert key to string
        new_responses = convert_responses_key_to_string(responses)
    if extra_responses is None:
        extra_responses = {}
    if security is None:
        security = []
    tags = tags + self.view_tags if tags else self.view_tags

    def decorator(func):
        if self.doc_ui is False or doc_ui is False:
            return
        # Global response combines API responses
        combine_responses = deepcopy(self.view_responses)
        combine_responses.update(**new_responses)
        # Create operation
        operation = get_operation(
            func,
            summary=summary,
            description=description,
            openapi_extensions=openapi_extensions
        )
        # Set external docs
        operation.externalDocs = external_docs
        # Unique string used to identify the operation.
        operation.operationId = operation_id
        # Only set `deprecated` if True, otherwise leave it as None
        operation.deprecated = deprecated
        # Add security
        operation.security = security + self.view_security or None
        # Add servers
        operation.servers = servers
        # Store tags
        parse_and_store_tags(tags, self.tags, self.tag_names, operation)
        # Parse parameters
        parse_parameters(
            func,
            extra_form=extra_form,
            extra_body=extra_body,
            components_schemas=self.components_schemas,
            operation=operation
        )
        # Parse response
        get_responses(combine_responses, extra_responses, self.components_schemas, operation)
        func.operation = operation

        return func

    return decorator

register(app, view_kwargs=None)

Register the API views with the given OpenAPI app.

Parameters:

Name	Type	Description	Default
app	OpenAPI	An instance of the OpenAPI app.	required
view_kwargs	Optional[Dict[Any, Any]]	Additional keyword arguments to pass to the API views.	None

Source code in flask_openapi3/view.py

def register(self, app: "OpenAPI", view_kwargs: Optional[Dict[Any, Any]] = None):
    """
    Register the API views with the given OpenAPI app.

    Args:
        app: An instance of the OpenAPI app.
        view_kwargs: Additional keyword arguments to pass to the API views.
    """
    if view_kwargs is None:
        view_kwargs = {}
    for rule, (cls, methods) in self.views.items():
        for method in methods:
            func = getattr(cls, method.lower())
            header, cookie, path, query, form, body = parse_parameters(func, doc_ui=False)
            view_func = app.create_view_func(
                func,
                header,
                cookie,
                path,
                query,
                form,
                body,
                view_class=cls,
                view_kwargs=view_kwargs
            )
            options = {
                "endpoint": cls.__name__ + "." + method.lower(),
                "methods": [method.upper()]
            }
            app.add_url_rule(rule, view_func=view_func, **options)

route(rule)

Decorator for view class

Source code in flask_openapi3/view.py

def route(self, rule: str):
    """Decorator for view class"""

    def wrapper(cls):
        if self.views.get(rule):
            raise ValueError(f"malformed url rule: {rule!r}")
        methods = []

        # Parse rule: merge url_prefix and format rule from /pet/<petId> to /pet/{petId}
        uri = parse_rule(rule, url_prefix=self.url_prefix)

        for method in HTTPMethod:
            cls_method = getattr(cls, method.lower(), None)
            if not cls_method:
                continue
            methods.append(method)
            if self.doc_ui is False:
                continue
            if not getattr(cls_method, "operation", None):
                continue
            # Parse method
            parse_method(uri, method, self.paths, cls_method.operation)
            # Update operation_id
            if not cls_method.operation.operationId:
                cls_method.operation.operationId = self.operation_id_callback(
                    name=cls_method.__qualname__,
                    path=rule,
                    method=method
                )

        # Convert route parameters from {param} to <param>
        _rule = uri.replace("{", "<").replace("}", ">")
        self.views[_rule] = (cls, methods)

        return cls

    return wrapper