Skip to content

[Java][jersey2] fix oneOf, anyOf documentation #6695

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

Merged
merged 4 commits into from
Jun 23, 2020
Merged

[Java][jersey2] fix oneOf, anyOf documentation #6695

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8015d28
fix oneOf doc in Java jersey2
wing328 Jun 17, 2020
6014c89
fix sample code
wing328 Jun 17, 2020
05d65d8
add new files
wing328 Jun 17, 2020
6884c16
minor tweat to the doc
wing328 Jun 17, 2020
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
38 changes: 38 additions & 0 deletions modules/openapi-generator/src/main/resources/Java/libraries/jersey2/model_anyof_doc.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# {{classname}}

{{#description}}
{{&description}}

{{/description}}
## anyOf schemas
{{#anyOf}}
* [{{{.}}}]({{{.}}}.md)
{{/anyOf}}

{{#isNullable}}
NOTE: this class is nullable.

{{/isNullable}}
## Example
```java
// Import classes:
import {{{package}}}.{{{classname}}};
{{#anyOf}}
import {{{package}}}.{{{.}}};
{{/anyOf}}

public class Example {
public static void main(String[] args) {
{{classname}} example{{classname}} = new {{classname}}();
{{#anyOf}}

// create a new {{{.}}}
{{{.}}} example{{{.}}} = new {{{.}}}();
// set {{{classname}}} to {{{.}}}
example{{classname}}.setActualInstance(example{{{.}}});
// to get back the {{{.}}} set earlier
{{{.}}} test{{{.}}} = ({{{.}}}) example{{classname}}.getActualInstance();
{{/anyOf}}
}
}
```
19 changes: 19 additions & 0 deletions modules/openapi-generator/src/main/resources/Java/libraries/jersey2/model_doc.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{{#models}}{{#model}}

{{#isEnum}}
{{>enum_outer_doc}}
{{/isEnum}}
{{^isEnum}}
{{^oneOf.isEmpty}}
{{>model_oneof_doc}}
Copy link
Contributor

@spacether spacether Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about when properties are set in the composed schema and we have oneOf or anyOf?

{{/oneOf.isEmpty}}
{{^anyOf.isEmpty}}
{{>model_anyof_doc}}
{{/anyOf.isEmpty}}
{{^anyOf}}
{{^oneOf}}
{{>pojo_doc}}
{{/oneOf}}
{{/anyOf}}
{{/isEnum}}
{{/model}}{{/models}}
38 changes: 38 additions & 0 deletions modules/openapi-generator/src/main/resources/Java/libraries/jersey2/model_oneof_doc.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# {{classname}}

{{#description}}
{{&description}}

{{/description}}
## oneOf schemas
{{#oneOf}}
* [{{{.}}}]({{{.}}}.md)
{{/oneOf}}
Copy link
Contributor

@spacether spacether Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about when we combine allOf and oneOf together?

Copy link
Member Author

@wing328 wing328 Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's step back. What does "combine allOf and oneOf together" really mean? Can you give an example of use case on that? What does the payload look like?

Copy link
Contributor

@spacether spacether Jun 17, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. A use case for this is when a user extracts common shared properties into a schema and they choose to have those properties stored in the oneOf schema as additionalProperties, not through allOf inheritance.
Let's look at an example:

EdibleInterface:
  type: object
  properties:
    calories:
      type: integer
Apple:
  type: object
  properties:
    color:
      type: string
    varietal:
      type: string
ComposedSchema:
  allOf:
    - $ref: '#/components/schemas/EdibleInterface'
  oneOf:
    - $ref: '#/components/schemas/Apple'

And a sample payload is:
{"calories": 110, "color": "yellow", "varietal": "golden delicious"}
At the ComposedSchema level, allOf validates + oneOf validates, and if we chose to return an instance of Apple when deserializing ComposedSchema, Apple includes the property calories as an additionalProperty.
Aren't json schema definitions additive?
ComposedSchema says that a payload must validate both EdibleInterface + Apple, schemas together, correct?

Copy link
Member Author

@wing328 wing328 Jun 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's focus on "ComposedSchema" and please forget about my implementation for the time being. Given the following:

ComposedSchema:
  allOf:
    - $ref: '#/components/schemas/EdibleInterface'
  oneOf:
    - $ref: '#/components/schemas/Apple'

oneOf and allOf are defined at the same level. Your understanding is that the properties defined in the oneOf schema are automatically unfolded and included in the object "ComposedSchema" (same level as the properties defined in the allOf schema), right?

Copy link
Contributor

@spacether spacether Jun 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's what I am trying to convey with the question
ComposedSchema says that a payload must validate both EdibleInterface + Apple, schemas together, correct?

Copy link
Member Author

@wing328 wing328 Jun 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assuming the answer to your question is yes, then the following is also valid, right?

ComposedSchema:
  allOf:
    - $ref: '#/components/schemas/EdibleInterface'
  oneOf:
    - type: string
    - type: integer

Does it make sense to you? If it does, what does the payload (e.g. JSON) look like?

Copy link
Contributor

@spacether spacether Jun 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that it can only be combined when they are of the same type. What do you think?
Because your example asks us to do this
3 + {"calories": 3}
Also, your example also applies to allof of different types which is not possible:
allOf:

  • Apple
  • integer

Copy link
Member Author

@wing328 wing328 Jun 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that it can only be combined when they are of the same type. What do you think?

My view is that it's not up to me (or you) whether there's such a rule to ensure the same type. It comes down to the definition in JSON schema. I may have missed it but I don't see such a rule explicitly (or implicitly) defined.

One more example. What about the following:

ComposedSchema:
  allOf:
    - $ref: '#/components/schemas/EdibleInterface'
  oneOf:
    - $ref: '#/components/schemas/Apple'
    - $ref: '#/components/schemas/Banana'
  oneOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Cat'

I assume it's also valid. Do you agree?

Copy link
Contributor

@spacether spacether Jun 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm isn't oneof a key? I thought that it was and that you can't have two of the same key.
Based on that thought, I think that it is not valid.
I will need to look at the spec to see what it says. Yup it is not up to us, I am asking about your understanding and interpretation.
Is allOf of mixed types valid to you? If so, what payload can meet those requirements?

Copy link
Contributor

@spacether spacether Jun 18, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the spec allof is defined as:
The OpenAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes an array of object definitions that are validated independently but together compose a single object.


{{#isNullable}}
NOTE: this class is nullable.

{{/isNullable}}
## Example
```java
// Import classes:
import {{{package}}}.{{{classname}}};
{{#oneOf}}
import {{{package}}}.{{{.}}};
{{/oneOf}}

public class Example {
public static void main(String[] args) {
{{classname}} example{{classname}} = new {{classname}}();
{{#oneOf}}

// create a new {{{.}}}
{{{.}}} example{{{.}}} = new {{{.}}}();
// set {{{classname}}} to {{{.}}}
example{{classname}}.setActualInstance(example{{{.}}});
// to get back the {{{.}}} set earlier
{{{.}}} test{{{.}}} = ({{{.}}}) example{{classname}}.getActualInstance();
{{/oneOf}}
}
}
```
36 changes: 29 additions & 7 deletions samples/openapi3/client/petstore/java/jersey2-java8/docs/Fruit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,36 @@

# Fruit

## Properties
## oneOf schemas
* [Apple](Apple.md)
* [Banana](Banana.md)

Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**color** | **String** | | [optional]
**cultivar** | **String** | | [optional]
**origin** | **String** | | [optional]
**lengthCm** | [**BigDecimal**](BigDecimal.md) | | [optional]
## Example
```java
// Import classes:
import org.openapitools.client.model.Fruit;
import org.openapitools.client.model.Apple;
import org.openapitools.client.model.Banana;

public class Example {
public static void main(String[] args) {
Fruit exampleFruit = new Fruit();

// create a new Apple
Apple exampleApple = new Apple();
// set Fruit to Apple
exampleFruit.setActualInstance(exampleApple);
// to get back the Apple set earlier
Apple testApple = (Apple) exampleFruit.getActualInstance();

// create a new Banana
Banana exampleBanana = new Banana();
// set Fruit to Banana
exampleFruit.setActualInstance(exampleBanana);
// to get back the Banana set earlier
Banana testBanana = (Banana) exampleFruit.getActualInstance();
}
}
```


38 changes: 31 additions & 7 deletions samples/openapi3/client/petstore/java/jersey2-java8/docs/FruitReq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,38 @@

# FruitReq

## Properties
## oneOf schemas
* [AppleReq](AppleReq.md)
* [BananaReq](BananaReq.md)

Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**cultivar** | **String** | |
**mealy** | **Boolean** | | [optional]
**lengthCm** | [**BigDecimal**](BigDecimal.md) | |
**sweet** | **Boolean** | | [optional]
NOTE: this class is nullable.

## Example
```java
// Import classes:
import org.openapitools.client.model.FruitReq;
import org.openapitools.client.model.AppleReq;
import org.openapitools.client.model.BananaReq;

public class Example {
public static void main(String[] args) {
FruitReq exampleFruitReq = new FruitReq();

// create a new AppleReq
AppleReq exampleAppleReq = new AppleReq();
// set FruitReq to AppleReq
exampleFruitReq.setActualInstance(exampleAppleReq);
// to get back the AppleReq set earlier
AppleReq testAppleReq = (AppleReq) exampleFruitReq.getActualInstance();

// create a new BananaReq
BananaReq exampleBananaReq = new BananaReq();
// set FruitReq to BananaReq
exampleFruitReq.setActualInstance(exampleBananaReq);
// to get back the BananaReq set earlier
BananaReq testBananaReq = (BananaReq) exampleFruitReq.getActualInstance();
}
}
```


36 changes: 29 additions & 7 deletions samples/openapi3/client/petstore/java/jersey2-java8/docs/GmFruit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,36 @@

# GmFruit

## Properties
## anyOf schemas
* [Apple](Apple.md)
* [Banana](Banana.md)

Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**color** | **String** | | [optional]
**cultivar** | **String** | | [optional]
**origin** | **String** | | [optional]
**lengthCm** | [**BigDecimal**](BigDecimal.md) | | [optional]
## Example
```java
// Import classes:
import org.openapitools.client.model.GmFruit;
import org.openapitools.client.model.Apple;
import org.openapitools.client.model.Banana;

public class Example {
public static void main(String[] args) {
GmFruit exampleGmFruit = new GmFruit();

// create a new Apple
Apple exampleApple = new Apple();
// set GmFruit to Apple
exampleGmFruit.setActualInstance(exampleApple);
// to get back the Apple set earlier
Apple testApple = (Apple) exampleGmFruit.getActualInstance();

// create a new Banana
Banana exampleBanana = new Banana();
// set GmFruit to Banana
exampleGmFruit.setActualInstance(exampleBanana);
// to get back the Banana set earlier
Banana testBanana = (Banana) exampleGmFruit.getActualInstance();
}
}
```


59 changes: 40 additions & 19 deletions samples/openapi3/client/petstore/java/jersey2-java8/docs/Mammal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,45 @@

# Mammal

## Properties

Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**hasBaleen** | **Boolean** | | [optional]
**hasTeeth** | **Boolean** | | [optional]
**className** | **String** | |
**type** | [**TypeEnum**](#TypeEnum) | | [optional]



## Enum: TypeEnum

Name | Value
---- | -----
PLAINS | "plains"
MOUNTAIN | "mountain"
GREVYS | "grevys"

## oneOf schemas
* [Pig](Pig.md)
* [Whale](Whale.md)
* [Zebra](Zebra.md)

## Example
```java
// Import classes:
import org.openapitools.client.model.Mammal;
import org.openapitools.client.model.Pig;
import org.openapitools.client.model.Whale;
import org.openapitools.client.model.Zebra;

public class Example {
public static void main(String[] args) {
Mammal exampleMammal = new Mammal();

// create a new Pig
Pig examplePig = new Pig();
// set Mammal to Pig
exampleMammal.setActualInstance(examplePig);
// to get back the Pig set earlier
Pig testPig = (Pig) exampleMammal.getActualInstance();

// create a new Whale
Whale exampleWhale = new Whale();
// set Mammal to Whale
exampleMammal.setActualInstance(exampleWhale);
// to get back the Whale set earlier
Whale testWhale = (Whale) exampleMammal.getActualInstance();

// create a new Zebra
Zebra exampleZebra = new Zebra();
// set Mammal to Zebra
exampleMammal.setActualInstance(exampleZebra);
// to get back the Zebra set earlier
Zebra testZebra = (Zebra) exampleMammal.getActualInstance();
}
}
```


37 changes: 32 additions & 5 deletions samples/openapi3/client/petstore/java/jersey2-java8/docs/NullableShape.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,39 @@
# NullableShape

The value may be a shape or the 'null' value. The 'nullable' attribute was introduced in OAS schema >= 3.0 and has been deprecated in OAS schema >= 3.1.
## Properties

Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**shapeType** | **String** | |
**quadrilateralType** | **String** | |
## oneOf schemas
* [Quadrilateral](Quadrilateral.md)
* [Triangle](Triangle.md)

NOTE: this class is nullable.

## Example
```java
// Import classes:
import org.openapitools.client.model.NullableShape;
import org.openapitools.client.model.Quadrilateral;
import org.openapitools.client.model.Triangle;

public class Example {
public static void main(String[] args) {
NullableShape exampleNullableShape = new NullableShape();

// create a new Quadrilateral
Quadrilateral exampleQuadrilateral = new Quadrilateral();
// set NullableShape to Quadrilateral
exampleNullableShape.setActualInstance(exampleQuadrilateral);
// to get back the Quadrilateral set earlier
Quadrilateral testQuadrilateral = (Quadrilateral) exampleNullableShape.getActualInstance();

// create a new Triangle
Triangle exampleTriangle = new Triangle();
// set NullableShape to Triangle
exampleNullableShape.setActualInstance(exampleTriangle);
// to get back the Triangle set earlier
Triangle testTriangle = (Triangle) exampleNullableShape.getActualInstance();
}
}
```


33 changes: 29 additions & 4 deletions samples/openapi3/client/petstore/java/jersey2-java8/docs/Pig.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,36 @@

# Pig

## Properties
## oneOf schemas
* [BasquePig](BasquePig.md)
* [DanishPig](DanishPig.md)

Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**className** | **String** | |
## Example
```java
// Import classes:
import org.openapitools.client.model.Pig;
import org.openapitools.client.model.BasquePig;
import org.openapitools.client.model.DanishPig;

public class Example {
public static void main(String[] args) {
Pig examplePig = new Pig();

// create a new BasquePig
BasquePig exampleBasquePig = new BasquePig();
// set Pig to BasquePig
examplePig.setActualInstance(exampleBasquePig);
// to get back the BasquePig set earlier
BasquePig testBasquePig = (BasquePig) examplePig.getActualInstance();

// create a new DanishPig
DanishPig exampleDanishPig = new DanishPig();
// set Pig to DanishPig
examplePig.setActualInstance(exampleDanishPig);
// to get back the DanishPig set earlier
DanishPig testDanishPig = (DanishPig) examplePig.getActualInstance();
}
}
```


Loading