0
# OpenAPI Models
1

2
Complete set of Pydantic models representing all OpenAPI 3.1.0 specification components. These models define the structure of API metadata, operation definitions, parameter specifications, schema objects, and other OpenAPI components.
3

4
## Capabilities
5

6
### Core Specification Models
7

8
Main models that define the overall API specification structure.
9

10
```python { .api }
11
class APISpec(BaseModel):
12
    """Root OpenAPI specification object"""
13
    openapi: str
14
    info: Info
15
    servers: Optional[list[Server]] = None
16
    paths: Paths
17
    components: Optional[Components] = None
18
    security: Optional[list[SecurityRequirement]] = None
19
    tags: Optional[list[Tag]] = None
20
    externalDocs: Optional[ExternalDocumentation] = None
21
    webhooks: Optional[dict[str, Union[PathItem, Reference]]] = None
22

23
class Components(BaseModel):
24
    """Reusable OpenAPI components"""
25
    schemas: Optional[dict[str, Union[Schema, Reference]]] = None
26
    responses: Optional[dict[str, Union[Response, Reference]]] = None
27
    parameters: Optional[dict[str, Union[Parameter, Reference]]] = None
28
    examples: Optional[dict[str, Union[Example, Reference]]] = None
29
    requestBodies: Optional[dict[str, Union[RequestBody, Reference]]] = None
30
    headers: Optional[dict[str, Union[Header, Reference]]] = None
31
    securitySchemes: Optional[dict[str, Union[SecurityScheme, Reference]]] = None
32
    links: Optional[dict[str, Union[Link, Reference]]] = None
33
    callbacks: Optional[dict[str, Union[Callback, Reference]]] = None
34
    pathItems: Optional[dict[str, Union[PathItem, Reference]]] = None
35

36
class Paths(BaseModel):
37
    """Available paths and operations"""
38
    # Dynamic paths are added as additional properties
39
    model_config = {"extra": "allow"}
40
```
41

42
### API Metadata Models
43

44
Models for describing API information, contact details, licensing, and external documentation.
45

46
```python { .api }
47
class Info(BaseModel):
48
    """API metadata and information"""
49
    title: str
50
    version: str
51
    description: Optional[str] = None
52
    termsOfService: Optional[str] = None
53
    contact: Optional[Contact] = None
54
    license: Optional[License] = None
55

56
class Contact(BaseModel):
57
    """Contact information for API"""
58
    name: Optional[str] = None
59
    url: Optional[str] = None
60
    email: Optional[str] = None
61

62
class License(BaseModel):
63
    """License information for API"""
64
    name: str
65
    identifier: Optional[str] = None
66
    url: Optional[str] = None
67

68
class ExternalDocumentation(BaseModel):
69
    """External documentation references"""
70
    description: Optional[str] = None
71
    url: str
72

73
class Tag(BaseModel):
74
    """API endpoint tags"""
75
    name: str
76
    description: Optional[str] = None
77
    externalDocs: Optional[ExternalDocumentation] = None
78
```
79

80
### Server Configuration Models
81

82
Models for defining API server information and variables.
83

84
```python { .api }
85
class Server(BaseModel):
86
    """Server information for API"""
87
    url: str
88
    description: Optional[str] = None
89
    variables: Optional[dict[str, ServerVariable]] = None
90

91
class ServerVariable(BaseModel):
92
    """Server variable definitions"""
93
    enum: Optional[list[str]] = None
94
    default: str
95
    description: Optional[str] = None
96
```
97

98
### Operation and Path Models
99

100
Models for defining API operations, paths, and their metadata.
101

102
```python { .api }
103
class Operation(BaseModel):
104
    """API operation specification"""
105
    tags: Optional[list[str]] = None
106
    summary: Optional[str] = None
107
    description: Optional[str] = None
108
    externalDocs: Optional[ExternalDocumentation] = None
109
    operationId: Optional[str] = None
110
    parameters: Optional[list[Union[Parameter, Reference]]] = None
111
    requestBody: Optional[Union[RequestBody, Reference]] = None
112
    responses: Optional[Responses] = None
113
    callbacks: Optional[dict[str, Union[Callback, Reference]]] = None
114
    deprecated: bool = False
115
    security: Optional[list[SecurityRequirement]] = None
116
    servers: Optional[list[Server]] = None
117

118
class PathItem(BaseModel):
119
    """Operations available on a single path"""
120
    ref: Optional[str] = Field(default=None, alias="$ref")
121
    summary: Optional[str] = None
122
    description: Optional[str] = None
123
    get: Optional[Operation] = None
124
    put: Optional[Operation] = None
125
    post: Optional[Operation] = None
126
    delete: Optional[Operation] = None
127
    options: Optional[Operation] = None
128
    head: Optional[Operation] = None
129
    patch: Optional[Operation] = None
130
    trace: Optional[Operation] = None
131
    servers: Optional[list[Server]] = None
132
    parameters: Optional[list[Union[Parameter, Reference]]] = None
133
```
134

135
### Parameter Models
136

137
Models for defining API parameters in different locations (path, query, header, cookie).
138

139
```python { .api }
140
class Parameter(BaseModel):
141
    """API parameter specification"""
142
    name: str
143
    in_: ParameterInType = Field(..., alias="in")
144
    description: Optional[str] = None
145
    required: bool = False
146
    deprecated: bool = False
147
    allowEmptyValue: bool = False
148
    style: Optional[StyleValues] = None
149
    explode: Optional[bool] = None
150
    allowReserved: bool = False
151
    schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
152
    example: Optional[Any] = None
153
    examples: Optional[dict[str, Union[Example, Reference]]] = None
154
    content: Optional[dict[str, MediaType]] = None
155

156
class Header(BaseModel):
157
    """Header parameter specification"""
158
    description: Optional[str] = None
159
    required: bool = False
160
    deprecated: bool = False
161
    allowEmptyValue: bool = False
162
    style: Optional[StyleValues] = None
163
    explode: Optional[bool] = None
164
    allowReserved: bool = False
165
    schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
166
    example: Optional[Any] = None
167
    examples: Optional[dict[str, Union[Example, Reference]]] = None
168
    content: Optional[dict[str, MediaType]] = None
169
```
170

171
### Request and Response Models
172

173
Models for defining request bodies and API responses.
174

175
```python { .api }
176
class RequestBody(BaseModel):
177
    """Request body specification"""
178
    description: Optional[str] = None
179
    content: dict[str, MediaType]
180
    required: bool = False
181

182
class Response(BaseModel):
183
    """API response specification"""
184
    description: str
185
    headers: Optional[dict[str, Union[Header, Reference]]] = None
186
    content: Optional[dict[str, MediaType]] = None
187
    links: Optional[dict[str, Union[Link, Reference]]] = None
188

189
class Responses(BaseModel):
190
    """Collection of response specifications"""
191
    default: Optional[Union[Response, Reference]] = None
192
    # HTTP status codes are added as additional properties
193
    model_config = {"extra": "allow"}
194
```
195

196
### Schema and Data Models
197

198
Models for defining data schemas, media types, and examples.
199

200
```python { .api }
201
class Schema(BaseModel):
202
    """JSON Schema definition"""
203
    # Schema properties follow JSON Schema specification
204
    title: Optional[str] = None
205
    multipleOf: Optional[float] = None
206
    maximum: Optional[float] = None
207
    exclusiveMaximum: Optional[bool] = None
208
    minimum: Optional[float] = None
209
    exclusiveMinimum: Optional[bool] = None
210
    maxLength: Optional[int] = Field(default=None, ge=0)
211
    minLength: Optional[int] = Field(default=None, ge=0)
212
    pattern: Optional[str] = None
213
    maxItems: Optional[int] = Field(default=None, ge=0)
214
    minItems: Optional[int] = Field(default=None, ge=0)
215
    uniqueItems: Optional[bool] = None
216
    maxProperties: Optional[int] = Field(default=None, ge=0)
217
    minProperties: Optional[int] = Field(default=None, ge=0)
218
    required: Optional[list[str]] = None
219
    enum: Optional[list[Any]] = None
220
    type: Optional[str] = None
221
    allOf: Optional[list[Union["Schema", Reference]]] = None
222
    oneOf: Optional[list[Union["Schema", Reference]]] = None
223
    anyOf: Optional[list[Union["Schema", Reference]]] = None
224
    not_: Optional[Union["Schema", Reference]] = Field(default=None, alias="not")
225
    items: Optional[Union["Schema", Reference]] = None
226
    properties: Optional[dict[str, Union["Schema", Reference]]] = None
227
    additionalProperties: Optional[Union[bool, "Schema", Reference]] = None
228
    description: Optional[str] = None
229
    format: Optional[str] = None
230
    default: Optional[Any] = None
231
    nullable: Optional[bool] = None
232
    discriminator: Optional[Discriminator] = None
233
    readOnly: Optional[bool] = None
234
    writeOnly: Optional[bool] = None
235
    example: Optional[Any] = None
236
    externalDocs: Optional[ExternalDocumentation] = None
237
    deprecated: Optional[bool] = None
238
    xml: Optional[XML] = None
239

240
class MediaType(BaseModel):
241
    """Media type definitions"""
242
    schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
243
    example: Optional[Any] = None
244
    examples: Optional[dict[str, Union[Example, Reference]]] = None
245
    encoding: Optional[dict[str, Encoding]] = None
246

247
class Example(BaseModel):
248
    """Example values for schema"""
249
    summary: Optional[str] = None
250
    description: Optional[str] = None
251
    value: Optional[Any] = None
252
    externalValue: Optional[str] = None
253

254
class Discriminator(BaseModel):
255
    """Discriminator for polymorphism"""
256
    propertyName: str
257
    mapping: Optional[dict[str, str]] = None
258

259
class XML(BaseModel):
260
    """XML metadata for schemas"""
261
    name: Optional[str] = None
262
    namespace: Optional[str] = None
263
    prefix: Optional[str] = None
264
    attribute: Optional[bool] = None
265
    wrapped: Optional[bool] = None
266

267
class Encoding(BaseModel):
268
    """Encoding property for request body"""
269
    contentType: Optional[str] = None
270
    headers: Optional[dict[str, Union[Header, Reference]]] = None
271
    style: Optional[StyleValues] = None
272
    explode: Optional[bool] = None
273
    allowReserved: Optional[bool] = None
274
```
275

276
### Security Models
277

278
Models for defining API security schemes and requirements.
279

280
```python { .api }
281
class SecurityScheme(BaseModel):
282
    """Security scheme definition"""
283
    type: str
284
    description: Optional[str] = None
285
    name: Optional[str] = None
286
    in_: Optional[str] = Field(default=None, alias="in")
287
    scheme: Optional[str] = None
288
    bearerFormat: Optional[str] = None
289
    flows: Optional[OAuthFlows] = None
290
    openIdConnectUrl: Optional[str] = None
291

292
class SecurityRequirement(BaseModel):
293
    """Security requirements for operations"""
294
    # Security scheme names are added as additional properties
295
    model_config = {"extra": "allow"}
296

297
class OAuthFlows(BaseModel):
298
    """OAuth2 flows configuration"""
299
    implicit: Optional[OAuthFlow] = None
300
    password: Optional[OAuthFlow] = None
301
    clientCredentials: Optional[OAuthFlow] = None
302
    authorizationCode: Optional[OAuthFlow] = None
303

304
class OAuthFlow(BaseModel):
305
    """OAuth2 flow configuration"""
306
    authorizationUrl: Optional[str] = None
307
    tokenUrl: Optional[str] = None
308
    refreshUrl: Optional[str] = None
309
    scopes: dict[str, str]
310

311
class OAuthConfig(BaseModel):
312
    """OAuth2 UI configuration"""
313
    clientId: Optional[str] = None
314
    clientSecret: Optional[str] = None
315
    realm: Optional[str] = None
316
    appName: Optional[str] = None
317
    scopeSeparator: Optional[str] = None
318
    scopes: Optional[str] = None
319
    additionalQueryStringParams: Optional[dict[str, str]] = None
320
    useBasicAuthenticationWithAccessCodeGrant: Optional[bool] = False
321
    usePkceWithAuthorizationCodeGrant: Optional[bool] = False
322
```
323

324
### Reference and Link Models
325

326
Models for referencing other components and defining operation relationships.
327

328
```python { .api }
329
class Reference(BaseModel):
330
    """Reference to another schema component"""
331
    ref: str = Field(..., alias="$ref")
332

333
class Link(BaseModel):
334
    """Link relationships between operations"""
335
    operationRef: Optional[str] = None
336
    operationId: Optional[str] = None
337
    parameters: Optional[dict[str, Any]] = None
338
    requestBody: Optional[Any] = None
339
    description: Optional[str] = None
340
    server: Optional[Server] = None
341

342
class Callback(BaseModel):
343
    """Callback object for webhooks"""
344
    # Expression names are added as additional properties
345
    model_config = {"extra": "allow"}
346
```
347

348
### Special Models
349

350
Models for file handling, validation errors, and raw data processing.
351

352
```python { .api }
353
class FileStorage(BaseModel):
354
    """File upload handling"""
355
    # Inherits from werkzeug.datastructures.FileStorage functionality
356
    # for handling multipart file uploads
357

358
class RawModel(Request):
359
    """Raw request data handling"""
360
    mimetypes: list[str] = ["application/json"]
361

362
class ValidationErrorModel(BaseModel):
363
    """Validation error response format"""
364
    detail: list[dict[str, Any]]
365

366
class UnprocessableEntity(BaseModel):
367
    """422 error response format"""
368
    detail: list[dict[str, Any]]
369
```
370

371
## Usage Examples
372

373
**Basic API Info Setup:**
374

375
```python
376
from flask_openapi3 import Info, Contact, License, Tag, Server
377

378
info = Info(
379
    title="My API",
380
    version="1.0.0",
381
    description="A sample API",
382
    contact=Contact(name="Developer", email="dev@example.com"),
383
    license=License(name="MIT")
384
)
385

386
tags = [
387
    Tag(name="users", description="User operations"),
388
    Tag(name="posts", description="Post operations")
389
]
390

391
servers = [
392
    Server(url="https://api.example.com", description="Production server"),
393
    Server(url="https://staging.example.com", description="Staging server")
394
]
395
```
396

397
**Response Model Definition:**
398

399
```python
400
from flask_openapi3 import Response as OpenAPIResponse
401
from pydantic import BaseModel
402

403
class User(BaseModel):
404
    id: int
405
    name: str
406
    email: str
407

408
class ErrorResponse(BaseModel):
409
    error: str
410
    message: str
411

412
# Define responses for endpoint
413
responses = {
414
    200: User,
415
    400: ErrorResponse,
416
    404: {"description": "User not found"}
417
}
418
```