Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use ObjectName as discriminator's mapping key #78

Merged
merged 3 commits into from
Nov 6, 2023
Merged

Use ObjectName as discriminator's mapping key #78

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
86e5c2a
fix(issue42): Add recommendation to use ObjectName as key in mapping …
patrice-conil Oct 20, 2023
4949c52
Update API-design-guidelines.md
rartych Oct 26, 2023
0c85d52
Merge branch 'main' into patrice-conil_issue42
rartych Nov 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions documentation/API-design-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1072,12 +1072,13 @@ In this part, the error response structure must also be defined, which must be a
</p>

#### 11.5.1 Usage of discriminator
As mentioned in Openapi doc [here](https://spec.openapis.org/oas/v3.0.3#discriminator-object) usage of discriminator may
As mentioned in OpenAPI doc [here](https://spec.openapis.org/oas/v3.0.3#discriminator-object) usage of discriminator may
simplify serialization/deserialization process and so reduce resource consumption.

##### Inheritance
The mappings section is not mandatory in discriminator, by default ClassName are used as values to populate the property. You can use mappings to restrict usage to a subset of subclasses.

The mappings section is not mandatory in discriminator, by default ClassName are used as values to populate the property. You can use mappings to restrict usage to subset of subclasses.
When it's possible, use Object Name as key in mapping section. This will simplify the work of providers and consumers who use OpenAPI code generators.

``` yaml
IpAddr:
Expand All @@ -1090,12 +1091,12 @@ The mappings section is not mandatory in discriminator, by default ClassName are
discriminator:
propertyName: addressType
mappings:
- IPV4ADDR: Ipv4Addr
- IPV6ADDR: Ipv6Addr
- Ipv4Addr: '#/components/schemas/Ipv4Addr' <-- use Object Name as mapping key to simplify usage
- Ipv6Addr: '#/components/schemas/Ipv6Addr'

Ipv4Addr:
Ipv4Addr: <-- Object Name also known as Class Name, used as JsonName by OpenAPI generator
allOf: <-- extends IpAddr (no need to define addressType because it's inherited
- $ref: IpAddr
- $ref: '#/components/schemas/IpAddr'
- type: object
required:
- address
Expand All @@ -1107,7 +1108,7 @@ The mappings section is not mandatory in discriminator, by default ClassName are

Ipv6Addr:
allOf: <-- extends IpAddr
- $ref: IpAddr
- $ref: '#/components/schemas/IpAddr'
- type: object
required:
- address
Expand Down