feat: [OpenAPI] oneOf with a Tensor (n-Dimensional array)

[rpanackal]

Context

#291

The PR focus on generating compilable code when multi dimentional arrays exist.

This PR does NOT fix the problem where there are multiple arrays under oneOf, but simply successfully generate a creator (annotated @JsonCreator) for a multi-dimentional array.

What does the PR solve?

Scenario 1: The oneOf contains only one array. But it is n-dim array, with n > 1.

• The PR fully solves this case by making it possible to generate compilable code. Since there is only one creator method, deserialization will also be successful for n-D arrays.

Scenario 2: The oneOf contains two array. Here dimensionality doesn't matter

• Here deserialization will fail because two conflicting creator methods.
• The PR partially address the problem by creating compilable code when any array has n>=2 dimensions.

Feature scope:

• Add capability to generate n-dimentional array of objects under oneOf. Effectively, when there is a single n-dim (n >=1) array, deserialization is successful.

Definition of Done

• Functionality scope stated & covered
• Tests cover the scope above
• Error handling created / updated & covered by the tests above
• Documentation updated
• Release notes updated

[rpanackal]

Question/Discussion

In the current state, we will be generating multiple creator methods like

create(Integer)
create(List<Integer>)
create2DList(List<List<Integer>>)

for the spec below:

OneOfExample
  oneOf
    - type: integer
    - type: array
      items:
         type: integer
   - type: array
     items:
        type: array
        items:
          type: integer

Though the above code compiles, deserialisation will fail at runtime.

I am not sure if we ideally,

1. Throw exception at code generation time for early detection because Jackson default deserializer will throw 100%

• Useful to fail our spec update workflow. Otherwise, such issues may be missed and hard to work around afterwards.

2. Dont throw an exception but log a warning (current state)

• Useful because the user may write their own custom deserializer/decoder on top

[newtork]

(Minor)

1. Can you combine arrayTypes1D and arrayTypesND? I don't see a reason why we need to maintain both sets(?)
2. Have you considered a record type instead of generic Map<String, String>? Looks a little lazy for storing 3 static values.

[newtork]

(Major/Discussion)

create2DList

I think that's a bad name. Unfortunately I do not have a good alternative at the moment.
I don't think we can use the terms dimension or matrix in our generator, because they indicate well defined m * n vectors, which does not really match the semantics of arrays of arbitrary size having elements of arrays of arbitrary size.

[newtork]

(Comment)

I think it's a bad idea to abuse the sample module das unit test ground. We should move it to generator module instead.
However since probably I'm offender too, I cannot force it here.
Maybe as part of a separate house-keeping PR.

[newtork]

(Comment)

You could also use the .isInstanceOfSatisfying API from AssertJ

Suggested change

	.isInstanceOf(OneOfWithMatrix.InnerIntegers2D.class);
	var integers2D = (OneOfWithMatrix.InnerIntegers2D) matrix;
	assertThat(integers2D.values()).isEqualTo(List.of(List.of(1, 2, 3), List.of(4, 5, 6)));
	.isInstanceOfSatisfying(
	OneOfWithMatrix.InnerIntegers2D.class,
	integers2D -> assertThat(integers2D.values()).isEqualTo(List.of(List.of(1, 2, 3), List.of(4, 5, 6))));