schon/engine/core/docs/drf/views.py

from django.conf import settings
from django.http import FileResponse
from django.utils.translation import gettext_lazy as _
from drf_spectacular.utils import OpenApiParameter, extend_schema, inline_serializer
from rest_framework import status
from rest_framework.fields import CharField, DictField, JSONField, ListField

from engine.core.docs.drf import error
from engine.core.serializers import (
    BuyAsBusinessOrderSerializer,
    CacheOperatorSerializer,
    ContactUsSerializer,
    LanguageSerializer,
)
from engine.payments.serializers import TransactionProcessSerializer


CUSTOM_OPENAPI_SCHEMA = {
    "get": extend_schema(
        tags=[
            "misc",
        ],
        parameters=[
            OpenApiParameter(
                name="lang",
                type=str,
                location="query",
                enum=list(dict(settings.LANGUAGES).keys()),
            ),
        ],
        summary=_("OpenAPI schema in selected format with selected language"),
        description=_(
            "OpenApi3 schema for this API. Format can be selected via content negotiation. "
            "Language can be selected with Accept-Language and query parameter both."
        ),
    )
}

CACHE_SCHEMA = {
    "post": extend_schema(
        tags=[
            "misc",
        ],
        summary=_("cache I/O"),
        description=_(
            "apply only a key to read permitted data from cache.\n"
            "apply key, data and timeout with authentication to write data to cache."
        ),
        request=CacheOperatorSerializer,
        responses={
            status.HTTP_200_OK: inline_serializer("cache", fields={"data": JSONField()}),
            status.HTTP_400_BAD_REQUEST: error,
        },
    ),
}

LANGUAGE_SCHEMA = {
    "get": extend_schema(
        tags=[
            "misc",
        ],
        summary=_("get a list of supported languages"),
        responses={
            status.HTTP_200_OK: LanguageSerializer(many=True),
        },
    )
}

PARAMETERS_SCHEMA = {
    "get": extend_schema(
        tags=[
            "misc",
        ],
        summary=_("get application's exposable parameters"),
        responses={status.HTTP_200_OK: inline_serializer("parameters", fields={"key": CharField(default="value")})},
    )
}

CONTACT_US_SCHEMA = {
    "post": extend_schema(
        tags=[
            "misc",
        ],
        summary=_("send a message to the support team"),
        request=ContactUsSerializer,
        responses={
            status.HTTP_200_OK: ContactUsSerializer,
            status.HTTP_400_BAD_REQUEST: error,
        },
    )
}

REQUEST_CURSED_URL_SCHEMA = {
    "post": extend_schema(
        tags=[
            "misc",
        ],
        summary=_("request a CORSed URL"),
        request=inline_serializer("url", fields={"url": CharField(default="https://example.org")}),
        responses={
            status.HTTP_200_OK: inline_serializer("data", fields={"data": JSONField()}),
            status.HTTP_400_BAD_REQUEST: error,
        },
    )
}

SEARCH_SCHEMA = {
    "get": extend_schema(
        tags=[
            "misc",
        ],
        summary=_("Search between products, categories and brands"),
        parameters=[
            OpenApiParameter(
                name="q",
                description="The search query string.",
                required=True,
                type=str,
            )
        ],
        responses={
            status.HTTP_200_OK: inline_serializer(
                name="GlobalSearchResponse",
                fields={"results": DictField(child=ListField(child=DictField(child=CharField())))},
            ),
            status.HTTP_400_BAD_REQUEST: inline_serializer(
                name="GlobalSearchErrorResponse", fields={"error": CharField()}
            ),
        },
        description=(_("global search endpoint to query across project's tables")),
    )
}

BUY_AS_BUSINESS_SCHEMA = {
    "post": extend_schema(
        tags=[
            "misc",
        ],
        summary=_("purchase an order as a business"),
        request=BuyAsBusinessOrderSerializer,
        responses={
            status.HTTP_201_CREATED: TransactionProcessSerializer,
            status.HTTP_400_BAD_REQUEST: error,
        },
        description=(
            _("purchase an order as a business, using the provided `products` with `product_uuid` and `attributes`.")
        ),
    )
}

DOWNLOAD_DIGITAL_ASSET_SCHEMA = {
    "get": extend_schema(
        tags=[
            "misc",
        ],
        parameters=[
            OpenApiParameter(
                name="order_product_uuid",
                location="path",
                required=True,
                allow_blank=False,
            )
        ],
        summary=_("download a digital asset from purchased digital order"),
        responses={
            status.HTTP_200_OK: FileResponse,
            status.HTTP_400_BAD_REQUEST: error,
        },
    )
}