1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
from __future__ import annotations
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any
from litestar.exceptions import ImproperlyConfiguredException
if TYPE_CHECKING:
from litestar.openapi.spec import Example
__all__ = ("ResponseHeader",)
@dataclass
class ResponseHeader:
"""Container type for a response header."""
name: str
"""Header name"""
documentation_only: bool = False
"""Defines the ResponseHeader instance as for OpenAPI documentation purpose only."""
value: str | None = None
"""Value to set for the response header."""
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
type 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.
[RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` 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: dict[str, Example] | 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.
"""
def __post_init__(self) -> None:
"""Ensure that either value is set or the instance is for documentation_only."""
if not self.documentation_only and self.value is None:
raise ImproperlyConfiguredException("value must be set if documentation_only is false")
def __hash__(self) -> int:
return hash(self.name)
|
