Rewrite Swagger Core's ModelResolver

[utybo]

Swagger Core's ModelResolver (which takes care of converting JVM types to JSON Schema types using Jackson and with a lot of custom logic) has a bunch of problems. It is very difficult to read (the function that performs the resolution is 750+ lines long of uninterrupted, fairly complex logic!), and, on the compatibility-with-Jackson side:

• Does not support custom enum serialization
• Does not support @JsonFormat

The idea would be to take the original code, convert it to Kotlin, split it in more understandable functions and provide it in a separate library. This honestly sounds like a fun challenge I'd be willing to take on[^why-not-contribute].

NB, if tests are present in Swagger Core's codebase, those must be taken into account. Add a lot of test, this reimplementation must have 100% coverage because it is a critical component of conversion.

In terms of integration into Tegral, provide it as a configuration flag (tegral.experiments.useNewSwaggerModelResolver or something) for Tegral and Ktor applications.

[^why-not-contribute]: I do not wish to contribute it back to Swagger Core as I would like to implement this complex logic in Kotlin to get the cleanest code possible (and I do not know how active Swagger Core is), while the original codebase is in Java.

---

The game plan

• Releases
  • 0.0.4: Include preliminary support
  • [ ] Ready?
  • [ ] Released?
  • v+1: General fixes and support
  • v+2: Stabilize, feature parity
  • v+3: Release as stable

Things to do

• [ ] Check all tests and find out what they test
• [ ] Check the coverage of the original implementation.
  • [ ] Report all uncovered sections
  • [ ] Imagine a test for each uncovered section
• [ ] Implement basic tests
• [ ] Implement an annotation system (probably with a separate annotation resolver mechanism)
  • [ ] Jackson support
  • [ ] kotlinx.serialization support
  • [ ] JaxB support

Swagger Core Tests

Tests to ignore

Because they don't test the resolver:

• AnnotationsUtilsExtensionsTest
• AnnotationsUtilsHeadersTest

ATMTest

• [ ] OK

• Simple class serialization

• Simple enum serialization

Test does not have useful assertions

BeanValidatorTest

• [ ] OK

• Normal field serialization

• Annotated fields serialization

  • Objects: NotNull
  • Integers: Min Max
  • String: Size Pattern
  • Decimals: DecimalMin DecimalMax
  • Collections: Size

ComplexPropertyTest

• [ ] OK

• Normal field serialization

• Field that uses another class

Test does not have useful assertions

ComposedSchemaTest

• [ ] OK

• Subclasses + one-of pattern

Test has useful assertions: yes

ContainerTest

• [ ] OK

• Serialization of collection fields

  • Array
  • Map

• Special serialization: java.util.Calendar

EnumTest

• [ ] OK

• Enum serialization

• Enum<?> serialization

HiddenFieldTest

• [ ] OK

• @Schema(hidden = true) serialization

• Serialization with @JsonCreator

InheritedBeanTest

• [ ] OK

• composedModelPropertiesAsSibling behavior

• JsonSubTypes support

JacksonJsonUnwrappedTest

• [ ] OK

• @JsonUnwrapped support

ModelWithJaxBDefaultValues

• [ ] OK

• @XmlElement(defaultValue = ...) support

JodaDateTimeConverterTest

• [ ] OK

• org.joda.time.DateTime support

JodaLocalDateConverterTest

• [ ] OK

• org.joda.time.LocalDate support

JodaTest

• [ ] OK

• org.joda.time.DateTime support

JsonPropertyTest

• [ ] OK

• JsonProperty support

ModelWithRangesTest

• [ ] OK

• @Schema ranges options support

RequiredFieldModelTest

• [ ] OK

• Tests of various ways to make fields required

SimpleGenerationTest

• [ ] OK

• Tests that fields are generated properly

2189

• [ ] OK

• JsonSubTypes support

2740 (Cyclic)

• [ ] OK

• Support of recursive data structures

2862

• [ ] OK

• JsonSubTypes support

2884

• [ ] OK

• JsonTypeInfo support

2915

• [ ] OK

• Not entirely sure of what this tests

2926

• Unrelated to OpenAPI

2972

• [ ] OK

• Not sure of what this tests

2992

• [ ] OK

• java.time LocalDateTime and LocalTime support

3030

• [ ] OK

• Annotations allOf + subTypes support

3063

• [ ] OK

• JsonTypeInfo + JsonSubTypes support

3197

• [ ] OK

• Schema with DiscriminatorMapping + JsonTypeInfo/JsonSubTypes with JsonSubTypes.Type

3348

• [ ] OK

• Object support

3365

• [ ] OK

• Not sure what this tests

3624

• [ ] OK

• Self referencing Optional<>

3697

• [ ] OK

• Hiding things via JsonCreator

3699

• [ ] OK

• Not sure, more JsonTypeInfo things

3703

• [ ] OK

• Self referencing optional

3853

• [ ] OK

• Not sure, more JsonTypeInfo things

3904

• [ ] OK

• @Schema in a @JsonValue

4290

• [ ] OK

• anyOf support

XMLGregorianCalendarTest

• [ ] OK

• javax.xml.datatype.XMLGregorianCalendar support

XMLInfoTest

• [ ] OK

• Various jaxb annotations support

XMLModelTest

• [ ] OK

• More jaxb annotations support

Extra things to care about

• All test beans must be kept in Java.

Kotlin support

• [ ] Ensure type system is used for schema nullability
• [ ] Automatic sealed class serialization support

Potential issues

• Classes may be associated too tightly with Jackson, making it difficult to integrate with other serialization annotations (e.g. kotlinx.serialization)

[utybo]

Pushing this back to an unknown date because this is extremely boring work, and I (currently) have no interest in working on this in my free time.