data-model-openapi30/src/MediaType.php at main · zero-to-prod/data-model-openapi30 · GitHub

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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
<?php

namespace Zerotoprod\DataModelOpenapi30;

use Zerotoprod\DataModel\Describe;
use Zerotoprod\DataModelOpenapi30\Helpers\DataModel;

/**
 * Each MediaType Type Object provides schema and examples for the media type
 * identified by its key.
 *
 * When `example` or `examples` are provided, the example _SHOULD_ match the
 * specified schema and be in the correct format as specified by the
 * media type and its encoding. The `example` and `examples` fields are
 * mutually exclusive, and if either is present it _SHALL_ override
 * any `example` in the schema. See Working With Examples for
 * further guidance regarding the different ways of
 * specifying examples, including non-JSON/YAML
 * values.
 *
 * @see  https://spec.openapis.org/oas/v3.0.4.html#media-type-object
 * @link https://github.com/zero-to-prod/data-model-openapi30
 */
class MediaType
{
    use DataModel;

    /**
     * The schema defining the content of the request, response, parameter, or header.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @see  $schema
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    public const schema = 'schema';

    /**
     * The schema defining the content of the request, response, parameter, or header.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    #[Describe(['cast' => [self::class, 'schema']])]
    public null|Schema|Reference $schema;

    /**
     * The schema defining the content of the request, response, parameter, or header.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @see  $schema
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    public static function schema($value, array $context): Schema|Reference|null
    {
        if (!isset($context[self::schema])) {
            return null;
        }

        return isset($value[Reference::ref])
            ? Reference::from($value)
            : Schema::from($value);
    }

    /**
     * Example of the media type; see Working With Examples.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @see  $example
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    public const example = 'example';

    /**
     * The schema defining the content of the request, response, parameter, or header.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    #[Describe(['nullable'])]
    public mixed $example;

    /**
     * Examples of the media type; see Working With Examples.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @see  $examples
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    public const examples = 'examples';

    /**
     * Examples of the media type; see Working With Examples.
     *
     * @var array<string, Example|Reference> $examples
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    #[Describe(['cast' => [self::class, 'examples']])]
    public array $examples;

    /**
     * Examples of the media type; see Working With Examples.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @see  $examples
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    public static function examples($value, array $context): array
    {
        return isset($context[self::examples])
            ? array_map(
                static fn($value) => isset($value[Reference::ref])
                    ? Reference::from($value)
                    : Example::from($value),
                $value
            )
            : [];
    }

    /**
     * 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` field _SHALL_ only apply to Request Body Objects,
     * and only when the media type is `multipart` or
     * `application/x-www-form-urlencoded`. If no
     * Encoding Object is provided for a property,
     * the behavior is determined by the default
     * values documented for the Encoding Object.
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @see  $encoding
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    public const encoding = 'encoding';

    /**
     * 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` field _SHALL_ only apply to Request Body Objects,
     * and only when the media type is `multipart` or
     * `application/x-www-form-urlencoded`. If no
     * Encoding Object is provided for a property,
     * the behavior is determined by the default
     * values documented for the Encoding Object.
     *
     * @var array<string, Encoding> $encoding
     *
     * @see  https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-11
     * @link https://github.com/zero-to-prod/data-model-openapi30
     */
    #[Describe([
        'cast' => [self::class, 'mapOf'],
        'type' => Encoding::class,
        'default' => []
    ])]
    public array $encoding;
}