search

ScaCap / spring-auto-restdocs

Spring Auto REST Docs is an extension to Spring REST Docs
https://scacap.github.io/spring-auto-restdocs/
Apache License 2.0
310 stars 86 forks source link

Support Java 14 Records #432

Closed fdutton closed 3 years ago

fdutton commented 3 years ago

Supporting Java 14 records requires two fundamental changes:

Unfortunately, this is complicated by the recent release of Jackson 2.12. This version of Jackson supports Java 14 records but it does so in a way that breaks existing custom ClassIntrospectors such as SardClassIntrospector.

fdutton commented 3 years ago

I have a pull-request ready but want to get some feed back on my approach before submitting it.

The first is satisfied easily enough with the introduction of a new module, spring-auto-restdocs-json-doclet-jdk14. As the name implies, it is a continuation of how support was added for JDK9 by creating the new module spring-auto-restdocs-json-doclet-jdk9.

The second is more difficult. This change must support JDKs prior to Java 14 using both Jackson 2.12 and above as well as Jackson prior to 2.12. It must also support Java 14 and later using both Jackson 2.12 and above as well as Jackson prior to 2.12.

I accomplished this by leveraging Java's ServiceLocator facility, which means that I created four new modules:

I'm not happy with this approach as it requires a user upgrading from Spring Auto-RestDocs 2.0.9 to 2.0.10 to include an additional dependency on _spring-auto-restdocs-jdk8-jackson_211. I'm open to any suggestions on how to mitigate this breaking change.

jmisur commented 3 years ago

Thanks for looking into this. It seems a bit complex and the PR is huge. I'm thinking how would it be possible to reduce into a single new dependency, e.g. jdk14, which would implicitly use jackson 2.12 since only that one supports all features of that jdk. However if Jackson broke an internal API, it's unlikely that they will release fixes to previous versions. Therefore I fear staying on < 2.12 branch would be unacceptable for us. By experimenting with Jackson 2.12, did you find any incompatibility with Spring RestDocs or other Spring component?

fdutton commented 3 years ago

Jackson 2.12.0 introduced a breaking API change that affected how auto-restdocs collects fields. I submitted a pull-request to restore the API and it was added to jackson-databind 2.12.1. I plan to rework this pull-request to use the new version and that should simplify it greatly. I just have not had the time to do it yet.

fdutton commented 3 years ago

I have submitted a new pull-request with a simpler approach. However, the initial build failed when using jackson-databind 2.12.2. I going to investigate if there is another breaking API change.

jmisur commented 3 years ago

Hi, I took a look at #437 and really like it. You even improved how we test the doclet itself. The only remaining concern for me is the Jackson version override. Did anything change in 2.12.x in regards to compatibility?

fdutton commented 3 years ago

Not that I know. I have updated the POM to allow a range of versions.

jmisur commented 3 years ago

Released in 2.0.11