django-bolt 0.1.0__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

django_bolt/openapi/spec/media_type.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .encoding import Encoding
+    from .example import Example
+    from .reference import Reference
+    from .schema import Schema
+
+__all__ = ("OpenAPIMediaType",)
+
+
+@dataclass
+class OpenAPIMediaType(BaseSchemaObject):
+    """Each Media Type Object provides schema and examples for the media type identified by its key."""
+
+    schema: Reference | Schema | None = None
+    """The schema defining the content of the request, response, or parameter."""
+
+    example: Any | None = None
+    """Example of the media type.
+
+    The example object SHOULD be in the correct format as specified by the media type.
+
+    The ``example`` field is mutually exclusive of the ``examples`` field.
+
+    Furthermore, if referencing a ``schema`` which contains an example, the ``example`` value SHALL _override_ the
+    example provided by the schema.
+    """
+
+    examples: dict[str, Example | Reference] | None = None
+    """Examples of the media type.
+
+    Each example object SHOULD match the media type and specified schema if present.
+
+    The ``examples`` field is mutually exclusive of the ``example`` field.
+
+    Furthermore, if referencing a ``schema`` which contains an example, the ``examples`` value SHALL _override_ the
+    example provided by the schema.
+    """
+
+    encoding: dict[str, Encoding] | None = None
+    """A map between a property name and its encoding information.
+
+    The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to
+    ``requestBody`` objects when the media type is ``multipart`` or ``application/x-www-form-urlencoded``.
+    """

django_bolt/openapi/spec/oauth_flow.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import BaseSchemaObject
+
+__all__ = ("OAuthFlow",)
+
+
+@dataclass
+class OAuthFlow(BaseSchemaObject):
+    """Configuration details for a supported OAuth Flow."""
+
+    authorization_url: str | None = None
+    """
+    **REQUIRED** for ``oauth2`` ("implicit", "authorizationCode"). The authorization URL to be used for this flow. This
+    MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+    """
+
+    token_url: str | None = None
+    """
+    **REQUIRED** for ``oauth2`` ("password", "clientCredentials", "authorizationCode"). The token URL to be used for
+    this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+    """
+
+    refresh_url: str | None = None
+    """The URL to be used for obtaining refresh tokens.
+
+    This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+    """
+
+    scopes: dict[str, str] | None = None
+    """
+    **REQUIRED** for ``oauth2``. The available scopes for the OAuth2 security scheme. A map between the scope name and a
+    short description for it the map MAY be empty.
+    """

django_bolt/openapi/spec/oauth_flows.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .oauth_flow import OAuthFlow
+
+__all__ = ("OAuthFlows",)
+
+
+@dataclass
+class OAuthFlows(BaseSchemaObject):
+    """Allows configuration of the supported OAuth Flows."""
+
+    implicit: OAuthFlow | None = None
+    """Configuration for the OAuth Implicit flow."""
+
+    password: OAuthFlow | None = None
+    """Configuration for the OAuth Resource Owner Password flow."""
+
+    client_credentials: OAuthFlow | None = None
+    """Configuration for the OAuth Client Credentials flow. Previously called ``application`` in OpenAPI 2.0."""
+
+    authorization_code: OAuthFlow | None = None
+    """Configuration for the OAuth Authorization Code flow. Previously called ``accessCode`` in OpenAPI 2.0."""

django_bolt/openapi/spec/open_api.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+from .components import Components
+from .server import Server
+
+if TYPE_CHECKING:
+    from .external_documentation import ExternalDocumentation
+    from .info import Info
+    from .path_item import PathItem
+    from .paths import Paths
+    from .reference import Reference
+    from .security_requirement import SecurityRequirement
+    from .tag import Tag
+
+__all__ = ("OpenAPI",)
+
+
+@dataclass
+class OpenAPI(BaseSchemaObject):
+    """Root OpenAPI document."""
+
+    info: Info
+    """
+    **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
+    """
+
+    openapi: str = "3.1.0"
+    """
+    **REQUIRED**. This string MUST be the
+    `version number <https://spec.openapis.org/oas/v3.1.0#versions>`_ of the OpenAPI Specification that the OpenAPI
+    document uses. The ``openapi`` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not*
+    related to the API `info.version <https://spec.openapis.org/oas/v3.1.0#infoVersion>`_ string.
+    """
+
+    json_schema_dialect: str | None = None
+    """The default value for the ``$schema`` keyword within
+    `Schema Objects <https://spec.openapis.org/oas/v3.1.0#schemaObject>`_ contained within this OAS document.
+
+    This MUST be in the form of a URI.
+    """
+
+    servers: list[Server] = field(default_factory=lambda x: [Server(url="/")])  # type: ignore[misc, arg-type]
+    """An array of Server Objects, which provide connectivity information to a target server.
+
+    If the ``servers`` property is not provided, or is an empty array, the default value would be a
+    `Server Object <https://spec.openapis.org/oas/v3.1.0#serverObject>`_ with a
+    `url <https://spec.openapis.org/oas/v3.1.0#serverUrl>`_ value of ``/``.
+    """
+
+    paths: Paths | None = None
+    """The available paths and operations for the API."""
+
+    webhooks: dict[str, PathItem | Reference] | None = None
+    """The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement.
+
+    Closely related to the ``callbacks`` feature, this section describes requests initiated other than by an API call,
+    for example by an out of band registration. The key name is a unique string to refer to each webhook, while the
+    (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the
+    expected responses. An
+    `example <https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml>`_ is available.
+    """
+
+    components: Components = field(default_factory=Components)
+    """An element to hold various schemas for the document."""
+
+    security: list[SecurityRequirement] | None = None
+    """A declaration of which security mechanisms can be used across the API.
+
+    The list of values includes alternative security requirement objects that can be used. Only one of the security
+    requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
+    To make security optional, an empty security requirement ( ``{}`` ) can be included in the array.
+    """
+
+    tags: list[Tag] | None = None
+    """A list of tags used by the document with additional metadata.
+
+    The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the
+    `Operation Object <https://spec.openapis.org/oas/v3.1.0#operationObject>`_ must be declared. The tags that are not
+    declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+    """
+
+    external_docs: ExternalDocumentation | None = None
+    """Additional external documentation."""

django_bolt/openapi/spec/operation.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .callback import Callback
+    from .external_documentation import ExternalDocumentation
+    from .parameter import Parameter
+    from .reference import Reference
+    from .request_body import RequestBody
+    from .responses import Responses
+    from .security_requirement import SecurityRequirement
+    from .server import Server
+
+__all__ = ("Operation",)
+
+
+@dataclass
+class Operation(BaseSchemaObject):
+    """Describes a single API operation on a path."""
+
+    tags: list[str] | None = None
+    """A list of tags for API documentation control.
+
+    Tags can be used for logical grouping of operations by resources or any other qualifier.
+    """
+
+    summary: str | None = None
+    """A short summary of what the operation does."""
+
+    description: str | None = None
+    """A verbose explanation of the operation behavior.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    external_docs: ExternalDocumentation | None = None
+    """Additional external documentation for this operation."""
+
+    operation_id: str | None = None
+    """Unique string used to identify the operation.
+
+    The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools
+    and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow
+    common programming naming conventions.
+    """
+
+    parameters: list[Parameter | Reference] | None = None
+    """A list of parameters that are applicable for this operation.
+
+    If a parameter is already defined at the `Path Item <https://spec.openapis.org/oas/v3.1.0#pathItemParameters>`_,
+    the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A
+    unique parameter is defined by a combination of a `name <https://spec.openapis.org/oas/v3.1.0#parameterName>`_ and
+    `location <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_. The list can use the
+    `Reference Object <https://spec.openapis.org/oas/v3.1.0#referenceObject>`_ to link to parameters that are defined at
+    the `OpenAPI Object's components/parameters <https://spec.openapis.org/oas/v3.1.0#componentsParameters>`_.
+    """
+
+    request_body: RequestBody | Reference | None = None
+    """The request body applicable for this operation.
+
+    The ``requestBody`` is fully supported in HTTP methods where the HTTP 1.1 specification
+    :rfc:`7231` has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such
+    as `GET <https://tools.ietf.org/html/rfc7231#section-4.3.1>`_,
+    `HEAD <https://tools.ietf.org/html/rfc7231#section-4.3.2>`_ and
+    `DELETE <https://tools.ietf.org/html/rfc7231#section-4.3.5>`_, ``requestBody`` is permitted but does not have
+    well-defined semantics and SHOULD be avoided if possible.
+    """
+
+    responses: Responses | None = None
+    """The list of possible responses as they are returned from executing this operation."""
+
+    callbacks: dict[str, Callback | Reference] | None = None
+    """A map of possible out-of band callbacks related to the parent operation.
+
+    The key is a unique identifier for the Callback Object. Each value in the map is a
+    `Callback Object <https://spec.openapis.org/oas/v3.1.0#callbackObject>`_ that describes a request that may be
+    initiated by the API provider and the expected responses.
+    """
+
+    deprecated: bool = False
+    """Declares this operation to be deprecated.
+
+    Consumers SHOULD refrain from usage of the declared operation. Default value is ``False``.
+    """
+
+    security: list[SecurityRequirement] | None = None
+    """A declaration of which security mechanisms can be used for this operation.
+
+    The list of values includes alternative security requirement objects that can be used. Only one of the security
+    requirement objects need to be satisfied to authorize a request. To make security optional, an empty security
+    requirement (``{}``) can be included in the array. This definition overrides any declared top-level
+    `security <https://spec.openapis.org/oas/v3.1.0#oasSecurity>`_. To remove a top-level security declaration, an empty
+    array can be used.
+    """
+
+    servers: list[Server] | None = None
+    """An alternative ``server`` array to service this operation.
+
+    If an alternative ``server`` object is specified at the Path Item Object or Root level, it will be overridden by
+    this value.
+    """

django_bolt/openapi/spec/parameter.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from .example import Example
+    from .media_type import OpenAPIMediaType
+    from .reference import Reference
+    from .schema import Schema
+
+__all__ = ("Parameter",)
+
+
+@dataclass
+class Parameter(BaseSchemaObject):
+    """Describes a single operation parameter.
+
+    A unique parameter is defined by a combination of a `name <https://spec.openapis.org/oas/v3.1.0#parameterName>`_ and
+    `location <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_.
+    """
+
+    name: str
+    """
+    **REQUIRED**. The name of the parameter.
+    Parameter names are *case sensitive*.
+
+    - If `in <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_ is ``"path"``, the ``name`` field MUST correspond to a
+      template expression occurring within the `path <https://spec.openapis.org/oas/v3.1.0#pathsPath>`_ field in the
+      `Paths Object <https://spec.openapis.org/oas/v3.1.0#pathsObject>`_. See
+      `Path Templating <https://spec.openapis.org/oas/v3.1.0#pathTemplating>`_ for further information.
+    - If `in <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_ is ``"header"`` and the ``name`` field is
+      ``"Accept"``, ``"Content-Type"`` or ``"Authorization"``, the parameter definition SHALL be ignored.
+    - For all other cases, the ``name`` corresponds to the parameter name used by the
+      `in <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_ property.
+    """
+
+    param_in: str
+    """
+    **REQUIRED**. The location of the parameter. Possible values are
+    ``"query"``, ``"header"``, ``"path"`` or ``"cookie"``.
+    """
+
+    schema: Schema | Reference | None = None
+    """The schema defining the type used for the parameter."""
+
+    description: str | None = None
+    """A brief description of the parameter. This could contain examples of
+    use.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    required: bool = False
+    """Determines whether this parameter is mandatory.
+
+    If the `parameter location <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_ is ``"path"``, this property is
+    **REQUIRED** and its value MUST be ``True``. Otherwise, the property MAY be included and its default value is
+    ``False``.
+    """
+
+    deprecated: bool = False
+    """Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
+
+    Default value is ``False``.
+    """
+
+    allow_empty_value: bool = False
+    """Sets the ability to pass empty-valued parameters. This is valid only for ``query`` parameters and allows sending
+    a parameter with an empty value. Default value is ``False``. If
+    `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__ is used, and if behavior is ``n/a`` (cannot be
+    serialized), the value of ``allowEmptyValue`` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is
+    likely to be removed in a later revision.
+
+    The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a
+    `schema <https://spec.openapis.org/oas/v3.1.0#parameterSchema>`_ and
+    `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__ can describe the structure and syntax of the
+    parameter.
+    """
+
+    style: str | None = None
+    """Describes how the parameter value will be serialized depending on the ype of the parameter value. Default values
+    (based on value of ``in``):
+
+    - for ``query`` - ``form``
+    - for ``path`` - ``simple``
+    - for ``header`` - ``simple``
+    - for ``cookie`` - ``form``
+    """
+
+    explode: bool | None = None
+    """When this is true, parameter values of type ``array`` or ``object`` generate separate parameters for each value
+    of the array or key-value pair of the map.
+
+    For other types of parameters this property has no effect. When
+    `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__ is ``form``, the default value is ``True``. For all
+    other styles, the default value is ``False``.
+    """
+
+    allow_reserved: bool = False
+    """Determines whether the parameter value SHOULD allow reserved characters, as defined by.
+
+    :rfc:`3986` ``:/?#[]@!$&'()*+,;=`` to be included without percent-encoding.
+
+    This property only applies to parameters with an ``in`` value of ``query``. The default value is ``False``.
+    """
+
+    example: Any | None = None
+    """Example of the parameter's potential value.
+
+    The example SHOULD match the specified schema and encoding properties if present. The ``example`` field is mutually
+    exclusive of the ``examples`` field. Furthermore, if referencing a ``schema`` that contains an example, the
+    ``example`` value SHALL _override_ the example provided by the schema. To represent examples of media types that
+    cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where
+    necessary.
+    """
+
+    examples: Mapping[str, Example | Reference] | None = None
+    """Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as
+    specified in the parameter encoding. The ``examples`` field is mutually exclusive of the ``example`` field.
+    Furthermore, if referencing a ``schema`` that contains an example, the ``examples`` value SHALL _override_ the
+    example provided by the schema.
+
+    For more complex scenarios, the `content <https://spec.openapis.org/oas/v3.1.0#parameterContent>`_ property can
+    define the media type and schema of the parameter. A parameter MUST contain either a ``schema`` property, or a
+    ``content`` property, but not both. When ``example`` or ``examples`` are provided in conjunction with the
+    ``schema`` object, the example MUST follow the prescribed serialization strategy for the parameter.
+    """
+
+    content: dict[str, OpenAPIMediaType] | None = None
+    """A map containing the representations for the parameter.
+
+    The key is the media type and the value describes it. The map MUST only contain one entry.
+    """
+
+    @property
+    def _exclude_fields(self) -> set[str]:
+        exclude = set()
+        if self.param_in != "query":
+            # these are only allowed in query params
+            exclude.update({"allow_empty_value", "allow_reserved"})
+
+        return exclude

django_bolt/openapi/spec/path_item.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .operation import Operation
+    from .parameter import Parameter
+    from .reference import Reference
+    from .server import Server
+
+__all__ = ("PathItem",)
+
+
+@dataclass
+class PathItem(BaseSchemaObject):
+    """Describes the operations available on a single path.
+
+    A Path Item MAY be empty, due to `ACL constraints <https://spec.openapis.org/oas/v3.1.0#securityFiltering>`_. The
+    path itself is still exposed to the documentation viewer, but they will not know which operations and parameters are
+    available.
+    """
+
+    ref: str | None = None
+    """Allows for an external definition of this path item. The referenced structure MUST be in the format of a
+    `Path Item Object <https://spec.openapis.org/oas/v3.1.0#pathItemObject>`.
+
+    In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is
+    undefined. See the rules for resolving
+    `Relative References <https://spec.openapis.org/oas/v3.1.0#relativeReferencesURI>`_.
+    """
+
+    summary: str | None = None
+    """An optional, string summary, intended to apply to all operations in this path."""
+
+    description: str | None = None
+    """An optional, string description, intended to apply to all operations in this path.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    get: Operation | None = None
+    """A definition of a GET operation on this path."""
+
+    put: Operation | None = None
+    """A definition of a PUT operation on this path."""
+
+    post: Operation | None = None
+    """A definition of a POST operation on this path."""
+
+    delete: Operation | None = None
+    """A definition of a DELETE operation on this path."""
+
+    options: Operation | None = None
+    """A definition of a OPTIONS operation on this path."""
+
+    head: Operation | None = None
+    """A definition of a HEAD operation on this path."""
+
+    patch: Operation | None = None
+    """A definition of a PATCH operation on this path."""
+
+    trace: Operation | None = None
+    """A definition of a TRACE operation on this path."""
+
+    servers: list[Server] | None = None
+    """An alternative ``server`` array to service all operations in this path."""
+
+    parameters: list[Parameter | Reference] | None = None
+    """A list of parameters that are applicable for all the operations described under this path. These parameters can
+    be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters.
+    A unique parameter is defined by a combination of a `name <https://spec.openapis.org/oas/v3.1.0#parameterName>`_ and
+    `location <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_. The list can use the
+    `Reference Object <https://spec.openapis.org/oas/v3.1.0#referenceObject>`_ to link to parameters that are defined at
+    the `OpenAPI Object's components/parameters <https://spec.openapis.org/oas/v3.1.0#componentsParameters>`_.
+    """

django_bolt/openapi/spec/paths.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .path_item import PathItem
+
+Paths = dict[str, "PathItem"]
+"""Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the.
+
+`Server Object <https://spec.openapis.org/oas/v3.1.0#serverObject>`_ in order to construct the full URL.
+
+The Paths MAY be empty, due to
+`Access Control List (ACL) constraints <https://spec.openapis.org/oas/v3.1.0#securityFiltering>`_.
+
+Patterned Fields
+
+/{path}: PathItem
+
+A relative path to an individual endpoint. The field name MUST begin with a forward slash (``/``). The path is
+**appended** (no relative URL resolution) to the expanded URL from the
+`Server Object <https://spec.openapis.org/oas/v3.1.0#serverObject>`_ 's ``url`` field in order to construct the full
+URL. `Path templating <https://spec.openapis.org/oas/v3.1.0#pathTemplating>`_ is allowed. When matching URLs, concrete
+(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but
+different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to
+decide which one to use.
+"""

django_bolt/openapi/spec/reference.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .base import BaseSchemaObject
+
+__all__ = ("Reference",)
+
+
+@dataclass
+class Reference(BaseSchemaObject):
+    """A simple object to allow referencing other components in the OpenAPI document, internally and externally.
+
+    The ``$ref`` string value contains a URI `RFC3986 <https://tools.ietf.org/html/rfc3986>`_ , which identifies the
+    location of the value being referenced.
+
+    See the rules for resolving `Relative References <https://spec.openapis.org/oas/v3.1.0#relativeReferencesURI>`_.
+    """
+
+    ref: str
+    """**REQUIRED**. The reference identifier. This MUST be in the form of a URI."""
+
+    summary: str | None = None
+    """A short summary which by default SHOULD override that of the referenced component.
+
+    If the referenced object-type does not allow a ``summary`` field, then this field has no effect.
+    """
+
+    description: str | None = None
+    """A description which by default SHOULD override that of the referenced component.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation. If the referenced
+    object-type does not allow a ``description`` field, then this field has no effect.
+    """
+
+    @property
+    def value(self) -> str:
+        return self.ref.split("/")[-1]

django_bolt/openapi/spec/request_body.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .base import BaseSchemaObject
+
+if TYPE_CHECKING:
+    from .media_type import OpenAPIMediaType
+
+__all__ = ("RequestBody",)
+
+
+@dataclass
+class RequestBody(BaseSchemaObject):
+    """Describes a single request body."""
+
+    content: dict[str, OpenAPIMediaType]
+    """
+    **REQUIRED**. The content of the request body.
+    The key is a media type or `media type range <https://tools.ietf.org/html/rfc7231#appendix-D>`_ and the value
+    describes it.
+
+    For requests that match multiple keys, only the most specific key is applicable. e.g. ``text/plain`` overrides
+    ``text/*``
+    """
+
+    description: str | None = None
+    """A brief description of the request body. This could contain examples of use.
+
+    `CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
+    """
+
+    required: bool = False
+    """Determines if the request body is required in the request.
+
+    Defaults to ``False``.
+    """