from __future__ import annotations
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any
from litestar.openapi.spec.base import BaseSchemaObject
if TYPE_CHECKING:
from litestar.openapi.spec.server import Server
__all__ = ("Link",)
[docs]
@dataclass
class Link(BaseSchemaObject):
"""The ``Link object`` represents a possible design-time link for a response. The presence of a link does not
guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal
mechanism between responses and other operations.
Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require
link information in the runtime response.
For computing links, and providing instructions to execute them, a
`runtime expression <https://spec.openapis.org/oas/v3.1.0#runtimeExpression>`_ is used for accessing values in an
operation and using them as parameters while invoking the linked operation.
"""
operation_ref: str | None = None
"""A relative or absolute URI reference to an OAS operation.
This field is mutually exclusive of the ``operationId`` field, and MUST point to an
`Operation Object <https://spec.openapis.org/oas/v3.1.0#operationObject>`_. Relative ``operationRef`` values MAY be
used to locate an existing `Operation Object <https://spec.openapis.org/oas/v3.1.0#operationObject>`_ in the OpenAPI
definition. See the rules for resolving
`Relative References <https://spec.openapis.org/oas/v3.1.0#relativeReferencesURI>`_
"""
operation_id: str | None = None
"""The name of an _existing_, resolvable OAS operation, as defined with a unique ``operationId``.
This field is mutually exclusive of the ``operationRef`` field.
"""
parameters: dict[str, Any] | None = None
"""A map representing parameters to pass to an operation as specified with ``operationId`` or identified via
``operationRef``. The key is the parameter name to be used, whereas the value can be a constant or an expression to
be evaluated and passed to the linked operation.
The parameter name can be qualified using the
`parameter location <https://spec.openapis.org/oas/v3.1.0#parameterIn>`_ ``[{in}.]{name}`` for operations that use
the same parameter name in different locations (e.g. path.id).
"""
request_body: Any | None = None
"""A literal value or
`{expression} <https://spec.openapis.org/oas/v3.1.0#runtimeExpression>`_ to use as a request body when calling the
target operation."""
description: str | None = None
"""A description of the link.
`CommonMark syntax <https://spec.commonmark.org/>`_ MAY be used for rich text representation.
"""
server: Server | None = None
"""A server object to be used by the target operation."""
Litestar