Skip to content

Commit ca1336f

Browse files
kuimonokuimono
authored
Merge pull request #3 from kuimono/openapi-v3.1.0
Openapi v3.1.0
2 parents 508bb53 + a2dead1 commit ca1336f

37 files changed

+2899
-8
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Change Log
22

3+
## v1.2.0 - 2021-06-28
4+
5+
### Added
6+
- Support OpenAPI schema v3.1.0
7+
8+
39
## v1.1.0 - 2020-05-28
410

511
### Added

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
OpenAPI (v3) specification schema as [Pydantic](https://github.com/samuelcolvin/pydantic) classes.
77

88
The naming of the classes follows the schema in
9-
[OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#schema).
9+
[OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schema).
1010

1111
## Installation
1212

@@ -42,7 +42,7 @@ Result:
4242

4343
```json
4444
{
45-
"openapi": "3.0.3",
45+
"openapi": "3.1.0",
4646
"info": {
4747
"title": "My own API",
4848
"version": "v0.0.1"
@@ -156,7 +156,7 @@ Result:
156156

157157
```json
158158
{
159-
"openapi": "3.0.3",
159+
"openapi": "3.1.0",
160160
"info": {
161161
"title": "My own API",
162162
"version": "v0.0.1"
@@ -264,6 +264,7 @@ More info about field alias:
264264

265265
| OpenAPI version | Field alias info |
266266
| --------------- | ---------------- |
267+
| 3.1.0 | [here](https://github.com/kuimono/openapi-schema-pydantic/blob/master/openapi_schema_pydantic/v3/v3_1_0/README.md#alias) |
267268
| 3.0.3 | [here](https://github.com/kuimono/openapi-schema-pydantic/blob/master/openapi_schema_pydantic/v3/v3_0_3/README.md#alias) |
268269

269270
### Non-pydantic schema types
@@ -273,6 +274,7 @@ Please refer to the following for more info:
273274

274275
| OpenAPI version | Non-pydantic schema type info |
275276
| --------------- | ----------------------------- |
277+
| 3.1.0 | [here](https://github.com/kuimono/openapi-schema-pydantic/blob/master/openapi_schema_pydantic/v3/v3_1_0/README.md#non-pydantic-schema-types) |
276278
| 3.0.3 | [here](https://github.com/kuimono/openapi-schema-pydantic/blob/master/openapi_schema_pydantic/v3/v3_0_3/README.md#non-pydantic-schema-types) |
277279

278280
## License

‎openapi_schema_pydantic/v3/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
from .v3_0_3 import *
1+
from .v3_1_0 import *

‎openapi_schema_pydantic/v3/v3_1_0/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# OpenAPI v3.1.0 schema classes
2+
3+
## Alias
4+
5+
Due to the reserved words in python and pydantic,
6+
the following fields are used with [alias](https://pydantic-docs.helpmanual.io/usage/schema/#field-customisation) feature provided by pydantic:
7+
8+
| Class | Field name in the class | Alias (as in OpenAPI spec) |
9+
| ----- | ----------------------- | -------------------------- |
10+
| Header[*](#header_param_in) | param_in | in |
11+
| MediaType | media_type_schema | schema |
12+
| Parameter | param_in | in |
13+
| Parameter | param_schema | schema |
14+
| PathItem | ref | $ref |
15+
| Reference | ref | $ref |
16+
| SecurityScheme | security_scheme_in | in |
17+
| Schema | schema_format | format |
18+
| Schema | schema_not | not |
19+
| Schema | schema_if | if |
20+
| Schema | schema_else | else |
21+
22+
> <a name="header_param_in"></a>The "in" field in Header object is actually a constant (`{"in": "header"}`).
23+
24+
> For convenience of object creation, the classes mentioned in above
25+
> has configured `allow_population_by_field_name=True`.
26+
>
27+
> Reference: [Pydantic's Model Config](https://pydantic-docs.helpmanual.io/usage/model_config/)
28+
29+
## Non-pydantic schema types
30+
31+
Due to the constriants of python typing structure (not able to handle dynamic field names),
32+
the following schema classes are actually just a typing of `Dict`:
33+
34+
| Schema Type | Implementation |
35+
| ----------- | -------------- |
36+
| Callback | `Callback = Dict[str, PathItem]` |
37+
| Paths | `Paths = Dict[str, PathItem]` |
38+
| Responses | `Responses = Dict[str, Union[Response, Reference]]` |
39+
| SecurityRequirement | `SecurityRequirement = Dict[str, List[str]]` |
40+
41+
On creating such schema instances, please use python's `dict` type instead to instantiate.

‎openapi_schema_pydantic/v3/v3_1_0/__init__.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
"""
2+
OpenAPI v3.1.0 schema types, created according to the specification:
3+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md
4+
5+
The type orders are according to the contents of the specification:
6+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#table-of-contents
7+
"""
8+
9+
from .open_api import OpenAPI
10+
from .info import Info
11+
from .contact import Contact
12+
from .license import License
13+
from .server import Server
14+
from .server_variable import ServerVariable
15+
from .components import Components
16+
from .paths import Paths
17+
from .path_item import PathItem
18+
from .operation import Operation
19+
from .external_documentation import ExternalDocumentation
20+
from .parameter import Parameter
21+
from .request_body import RequestBody
22+
from .media_type import MediaType
23+
from .encoding import Encoding
24+
from .responses import Responses
25+
from .response import Response
26+
from .callback import Callback
27+
from .example import Example
28+
from .link import Link
29+
from .header import Header
30+
from .tag import Tag
31+
from .reference import Reference
32+
from .schema import Schema
33+
from .discriminator import Discriminator
34+
from .xml import XML
35+
from .security_scheme import SecurityScheme
36+
from .oauth_flows import OAuthFlows
37+
from .oauth_flow import OAuthFlow
38+
from .security_requirement import SecurityRequirement

‎openapi_schema_pydantic/v3/v3_1_0/callback.py‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
from typing import Dict, Union
2+
3+
from .reference import Reference
4+
5+
6+
Callback = Dict[str, Union["PathItem", Reference]]
7+
"""
8+
A map of possible out-of band callbacks related to the parent operation.
9+
Each value in the map is a [Path Item Object](#pathItemObject)
10+
that describes a set of requests that may be initiated by the API provider and the expected responses.
11+
The key value used to identify the path item object is an expression, evaluated at runtime,
12+
that identifies a URL to use for the callback operation.
13+
"""
14+
15+
"""Patterned Fields"""
16+
17+
# {expression}: 'PathItem' = ...
18+
"""
19+
A Path Item Object used to define a callback request and expected responses.
20+
21+
A [complete example](../examples/v3.0/callback-example.yaml) is available.
22+
"""

‎openapi_schema_pydantic/v3/v3_1_0/components.py‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
from typing import Dict, Optional, Union
2+
3+
from pydantic import BaseModel, Extra
4+
5+
from .callback import Callback
6+
from .example import Example
7+
from .header import Header
8+
from .link import Link
9+
from .parameter import Parameter
10+
from .path_item import PathItem
11+
from .reference import Reference
12+
from .request_body import RequestBody
13+
from .response import Response
14+
from .schema import Schema
15+
from .security_scheme import SecurityScheme
16+
17+
18+
class Components(BaseModel):
19+
"""
20+
Holds a set of reusable objects for different aspects of the OAS.
21+
All objects defined within the components object will have no effect on the API
22+
unless they are explicitly referenced from properties outside the components object.
23+
"""
24+
25+
schemas: Optional[Dict[str, Schema]] = None
26+
"""An object to hold reusable [Schema Objects](#schemaObject)."""
27+
28+
responses: Optional[Dict[str, Union[Response, Reference]]] = None
29+
"""An object to hold reusable [Response Objects](#responseObject)."""
30+
31+
parameters: Optional[Dict[str, Union[Parameter, Reference]]] = None
32+
"""An object to hold reusable [Parameter Objects](#parameterObject)."""
33+
34+
examples: Optional[Dict[str, Union[Example, Reference]]] = None
35+
"""An object to hold reusable [Example Objects](#exampleObject)."""
36+
37+
requestBodies: Optional[Dict[str, Union[RequestBody, Reference]]] = None
38+
"""An object to hold reusable [Request Body Objects](#requestBodyObject)."""
39+
40+
headers: Optional[Dict[str, Union[Header, Reference]]] = None
41+
"""An object to hold reusable [Header Objects](#headerObject)."""
42+
43+
securitySchemes: Optional[Dict[str, Union[SecurityScheme, Reference]]] = None
44+
"""An object to hold reusable [Security Scheme Objects](#securitySchemeObject)."""
45+
46+
links: Optional[Dict[str, Union[Link, Reference]]] = None
47+
"""An object to hold reusable [Link Objects](#linkObject)."""
48+
49+
callbacks: Optional[Dict[str, Union[Callback, Reference]]] = None
50+
"""An object to hold reusable [Callback Objects](#callbackObject)."""
51+
52+
pathItems: Optional[Dict[str, Union[PathItem, Reference]]] = None
53+
"""An object to hold reusable [Path Item Object](#pathItemObject)."""
54+
55+
class Config:
56+
extra = Extra.forbid
57+
schema_extra = {
58+
"examples": [
59+
{
60+
"schemas": {
61+
"GeneralError": {
62+
"type": "object",
63+
"properties": {
64+
"code": {"type": "integer", "format": "int32"},
65+
"message": {"type": "string"},
66+
},
67+
},
68+
"Category": {
69+
"type": "object",
70+
"properties": {"id": {"type": "integer", "format": "int64"}, "name": {"type": "string"}},
71+
},
72+
"Tag": {
73+
"type": "object",
74+
"properties": {"id": {"type": "integer", "format": "int64"}, "name": {"type": "string"}},
75+
},
76+
},
77+
"parameters": {
78+
"skipParam": {
79+
"name": "skip",
80+
"in": "query",
81+
"description": "number of items to skip",
82+
"required": True,
83+
"schema": {"type": "integer", "format": "int32"},
84+
},
85+
"limitParam": {
86+
"name": "limit",
87+
"in": "query",
88+
"description": "max records to return",
89+
"required": True,
90+
"schema": {"type": "integer", "format": "int32"},
91+
},
92+
},
93+
"responses": {
94+
"NotFound": {"description": "Entity not found."},
95+
"IllegalInput": {"description": "Illegal input for operation."},
96+
"GeneralError": {
97+
"description": "General Error",
98+
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GeneralError"}}},
99+
},
100+
},
101+
"securitySchemes": {
102+
"api_key": {"type": "apiKey", "name": "api_key", "in": "header"},
103+
"petstore_auth": {
104+
"type": "oauth2",
105+
"flows": {
106+
"implicit": {
107+
"authorizationUrl": "http://example.org/api/oauth/dialog",
108+
"scopes": {
109+
"write:pets": "modify pets in your account",
110+
"read:pets": "read your pets",
111+
},
112+
}
113+
},
114+
},
115+
},
116+
}
117+
]
118+
}

‎openapi_schema_pydantic/v3/v3_1_0/contact.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
from typing import Optional
2+
3+
from pydantic import AnyUrl, BaseModel, Extra
4+
5+
6+
class Contact(BaseModel):
7+
"""
8+
Contact information for the exposed API.
9+
"""
10+
11+
name: Optional[str] = None
12+
"""
13+
The identifying name of the contact person/organization.
14+
"""
15+
16+
url: Optional[AnyUrl] = None
17+
"""
18+
The URL pointing to the contact information.
19+
MUST be in the form of a URL.
20+
"""
21+
22+
email: Optional[str] = None
23+
"""
24+
The email address of the contact person/organization.
25+
MUST be in the form of an email address.
26+
"""
27+
28+
class Config:
29+
extra = Extra.forbid
30+
schema_extra = {
31+
"examples": [
32+
{"name": "API Support", "url": "http://www.example.com/support", "email": "[email protected]"}
33+
]
34+
}

‎openapi_schema_pydantic/v3/v3_1_0/discriminator.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
from typing import Dict, Optional
2+
3+
from pydantic import BaseModel, Extra
4+
5+
6+
class Discriminator(BaseModel):
7+
"""
8+
When request bodies or response payloads may be one of a number of different schemas,
9+
a `discriminator` object can be used to aid in serialization, deserialization, and validation.
10+
11+
The discriminator is a specific object in a schema which is used to inform the consumer of the specification
12+
of an alternative schema based on the value associated with it.
13+
14+
When using the discriminator, _inline_ schemas will not be considered.
15+
"""
16+
17+
propertyName: str = ...
18+
"""
19+
**REQUIRED**. The name of the property in the payload that will hold the discriminator value.
20+
"""
21+
22+
mapping: Optional[Dict[str, str]] = None
23+
"""
24+
An object to hold mappings between payload values and schema names or references.
25+
"""
26+
27+
class Config:
28+
extra = Extra.forbid
29+
schema_extra = {
30+
"examples": [
31+
{
32+
"propertyName": "petType",
33+
"mapping": {
34+
"dog": "#/components/schemas/Dog",
35+
"monster": "https://gigantic-server.com/schemas/Monster/schema.json",
36+
},
37+
}
38+
]
39+
}

0 commit comments

Comments
 (0)