specification.py

"""OpenAPI specification data models."""

from dataclasses import dataclass, field
from typing import Any

from openapi_parser.enumeration import (
    AuthenticationScheme,
    BaseLocation,
    ContentType,
    CookieParameterStyle,
    DataType,
    HeaderParameterStyle,
    IntegerFormat,
    NumberFormat,
    OAuthFlowType,
    OperationMethod,
    ParameterLocation,
    PathParameterStyle,
    QueryParameterStyle,
    SecurityType,
    StringFormat,
)
from openapi_parser.loose_types import (
    LooseContentType,
    LooseIntegerFormat,
    LooseNumberFormat,
    LooseStringFormat,
)


@dataclass(frozen=True, slots=True)
class Contact:
    """API contact information."""

    name: str | None = None
    url: str | None = None
    email: str | None = None


@dataclass(frozen=True, slots=True)
class License:
    """API license information."""

    name: str
    url: str | None = None
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Info:
    """API metadata information."""

    title: str
    version: str
    description: str | None = None
    terms_of_service: str | None = None
    contact: Contact | None = None
    license: License | None = None
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Server:
    """API server definition."""

    url: str
    description: str | None = None
    variables: dict[str, Any] | None = field(default_factory=dict)
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class ExternalDoc:
    """External documentation reference."""

    url: str
    description: str | None = None
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Schema:
    """Base schema model."""

    type: DataType
    title: str | None = None
    enum: list[Any] | None = field(default_factory=list)
    example: Any | None = None
    description: str | None = None
    default: Any | None = None
    nullable: bool | None = field(default=False)
    read_only: bool | None = field(default=False)
    write_only: bool | None = field(default=False)
    deprecated: bool | None = field(default=False)
    not_schema: "Schema | None" = None
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Integer(Schema):
    """Integer type schema."""

    multiple_of: int | None = None
    maximum: int | None = None
    exclusive_maximum: int | None = None
    minimum: int | None = None
    exclusive_minimum: int | None = None
    format: IntegerFormat | LooseIntegerFormat | None = None


@dataclass(frozen=True, slots=True)
class Number(Schema):
    """Number type schema."""

    multiple_of: float | None = None
    maximum: float | None = None
    exclusive_maximum: float | None = None
    minimum: float | None = None
    exclusive_minimum: float | None = None
    format: NumberFormat | LooseNumberFormat | None = None


@dataclass(frozen=True, slots=True)
class String(Schema):
    """String type schema."""

    max_length: int | None = None
    min_length: int | None = None
    pattern: str | None = None
    format: StringFormat | LooseStringFormat | None = None


@dataclass(frozen=True, slots=True)
class Null(Schema):
    """Null type schema."""

    pass


@dataclass(frozen=True, slots=True)
class Boolean(Schema):
    """Boolean type schema."""

    pass


@dataclass(frozen=True, slots=True)
class Array(Schema):
    """Array type schema."""

    max_items: int | None = None
    min_items: int | None = None
    unique_items: bool | None = None
    items: Schema | None = None


@dataclass(frozen=True, slots=True)
class Discriminator:
    """Polymorphism discriminator."""

    property_name: str
    mapping: dict[str, str] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class OneOf(Schema):
    """OneOf composition schema."""

    schemas: list[Schema] = field(default_factory=list)
    discriminator: Discriminator | None = None


@dataclass(frozen=True, slots=True)
class AnyOf(Schema):
    """AnyOf composition schema."""

    schemas: list[Schema] = field(default_factory=list)
    discriminator: Discriminator | None = None


@dataclass(frozen=True, slots=True)
class Property:
    """Schema property definition."""

    name: str
    schema: Schema


@dataclass(frozen=True, slots=True)
class Object(Schema):
    """Object type schema."""

    max_properties: int | None = None
    min_properties: int | None = None
    required: list[str] = field(default_factory=list)
    properties: list[Property] = field(default_factory=list)
    additional_properties: bool | Schema | None = None


@dataclass(frozen=True, slots=True)
class Parameter:
    """API parameter definition."""

    name: str
    location: ParameterLocation
    schema: Schema | None = None
    content: "list[Content] | None" = None
    required: bool | None = field(default=False)
    description: str | None = None
    example: Any | None = None
    examples: dict[str, Any] = field(default_factory=dict)
    allow_reserved: bool | None = None
    deprecated: bool | None = field(default=False)
    style: (
        str
        | PathParameterStyle
        | QueryParameterStyle
        | HeaderParameterStyle
        | CookieParameterStyle
        | None
    ) = None
    explode: bool | None = field(default=False)
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Encoding:
    """Encoding definition for request body properties."""

    content_type: str | None = None
    headers: "list[Header]" = field(default_factory=list)
    style: str | None = None
    explode: bool | None = None
    allow_reserved: bool | None = None
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Content:
    """Request/response content definition."""

    type: ContentType | LooseContentType
    schema: Schema
    example: Any | None = None
    examples: dict[str, Any] = field(default_factory=dict)
    encoding: dict[str, Encoding] | None = None


@dataclass(frozen=True, slots=True)
class RequestBody:
    """Request body definition."""

    content: list[Content]
    description: str | None = None
    required: bool | None = field(default=False)


@dataclass(frozen=True, slots=True)
class Header:
    """Response header definition."""

    name: str
    schema: Schema
    description: str | None = None
    required: bool | None = field(default=False)
    deprecated: bool | None = field(default=False)
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Link:
    """Link definition for response links."""

    operation_ref: str | None = None
    operation_id: str | None = None
    parameters: dict[str, Any] = field(default_factory=dict)
    request_body: Any | None = None
    description: str | None = None
    server: Server | None = None
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Response:
    """API response definition."""

    is_default: bool
    description: str
    code: int | None = None
    content: list[Content] | None = None
    headers: list[Header] = field(default_factory=list)
    links: dict[str, Link] | None = None


@dataclass(frozen=True, slots=True)
class OAuthFlow:
    """OAuth flow definition."""

    refresh_url: str | None = None
    authorization_url: str | None = None
    token_url: str | None = None
    scopes: dict[str, str] = field(default_factory=dict)
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Security:
    """Security scheme definition."""

    type: SecurityType
    location: BaseLocation | None = None
    description: str | None = None
    name: str | None = None
    scheme: AuthenticationScheme | None = None
    bearer_format: str | None = None
    flows: dict[OAuthFlowType, OAuthFlow] = field(default_factory=dict)
    url: str | None = None
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Operation:
    """API operation definition."""

    method: OperationMethod
    responses: list[Response]
    summary: str | None = None
    description: str | None = None
    operation_id: str | None = None
    external_docs: ExternalDoc | None = None
    request_body: RequestBody | None = None
    deprecated: bool | None = field(default=False)
    parameters: list[Parameter] = field(default_factory=list)
    tags: list[str] = field(default_factory=list)
    security: list[dict[str, Any]] = field(default_factory=list)
    extensions: dict[str, Any] | None = field(default_factory=dict)
    callbacks: dict[str, Any] = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Path:
    """API path definition."""

    url: str
    summary: str | None = None
    description: str | None = None
    operations: list[Operation] = field(default_factory=list)
    parameters: list[Parameter] = field(default_factory=list)
    extensions: dict[str, Any] | None = field(default_factory=dict)


@dataclass(frozen=True, slots=True)
class Tag:
    """API tag definition."""

    name: str
    description: str | None = None
    external_docs: ExternalDoc | None = None


@dataclass(frozen=True, slots=True)
class Specification:
    """Root OpenAPI specification object."""

    version: str
    info: Info
    servers: list[Server] = field(default_factory=list)
    tags: list[Tag] = field(default_factory=list)
    security_schemas: dict[str, Security] = field(default_factory=dict)
    security: list[dict[str, Any]] = field(default_factory=list)
    schemas: dict[str, Schema] = field(default_factory=dict)
    external_docs: ExternalDoc | None = None
    paths: list[Path] = field(default_factory=list)
    extensions: dict[str, Any] | None = field(default_factory=dict)