From 86e5c2ab963ea4054b3ee7e7bdda261e64713bd8 Mon Sep 17 00:00:00 2001 From: Patrice Conil Date: Fri, 20 Oct 2023 08:37:30 +0200 Subject: [PATCH 1/2] fix(issue42): Add recommendation to use ObjectName as key in mapping section of discriminators. Signed-off-by: Patrice Conil --- documentation/API-design-guidelines.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 79b70823..5c5430e1 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1077,7 +1077,7 @@ simplify serialization/deserialization process and so reduce resource consumptio ##### 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 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 generators. ``` yaml IpAddr: @@ -1090,12 +1090,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 @@ -1107,7 +1107,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 From 4949c52434316c6dce91c26f57ea7e6492cf774c Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Thu, 26 Oct 2023 17:46:58 +0200 Subject: [PATCH 2/2] Update API-design-guidelines.md openapi --> OpenAPI --- documentation/API-design-guidelines.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 5c5430e1..b485a1eb 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1072,12 +1072,12 @@ In this part, the error response structure must also be defined, which must be a

#### 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 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 generators. +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: @@ -1093,7 +1093,7 @@ When it's possible, use Object Name as key in mapping section. This will simplif - Ipv4Addr: '#/components/schemas/Ipv4Addr' <-- use Object Name as mapping key to simplify usage - Ipv6Addr: '#/components/schemas/Ipv6Addr' - Ipv4Addr: <-- Object Name also known as Class Name, used as JsonName by openapi generator + 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: '#/components/schemas/IpAddr' - type: object