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¹.

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.

---

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)

Footnotes

1. 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. ↩

[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.