Moving to open api spec 3.1

[alamers]

Related to #214, the question pops up whether or not to move our spec to OpenAPi 3.1.

Two main questions on this topic:

• Does this impact (runtime) backwards compatibility? (expectation: no)
• What is our policy on following the OpenApi spec? What can our partners expect with regards to maintaining a stable tool stack?

[ahokkonen]

Things to review for migration: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0

Also to notice - currently not all generators supports OAS3.1 so the migration should be considered carefully.

[alamers]

As discussed in the meeting today, investigating will continue but we don't expect 3.1 to be used for the next version. Version 3.0 will be the openapi spec to use for now.

[cookeac]

The group members at a meeting on 23 Sep 2021 discussed a move to support OpenAPI 3.1
(release announcement here: https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released)

Our policy will be to move to newer versions providing that there is tool chain support from the commonly used toolchains by implementers across the wider ICAR group.

At present we cannot move as we await open-api generator support for OpenAPI spec 3.1. In turn this depends on when swagger-parser Supports OAS 3.1.

[cookeac]

Discussed this with reference to #409 which would require OAS3.1
OAS3.1 is now fully supported by open-api generator and other tooling. It better supports the elements of JSON Schema, and better supports documentation and examples.

Recommended a move to support OAS 3.1 within the timeline of ADE 1.4, subject to checking the way that code generation, particularly of the change from nullable to a [null] type option, is handled in C# and Java.
@AlexeyHardCode and @AndreasSchultzGEA we hope you could test this with just one or two files in your code generation.

[cookeac]

Noted also that use of GeoJSON's geometry type in #430 would also require OpenAPI 3.1 as it uses a $schema and $id specification that is not supported in OpenAPI 3.0.

[AndreasSchultzGEA]

In general, I managed to create the Java-DTOs from the JSON-definitions....
But I couldn't test them, because the interface-generation still makes trouble:

    at jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke (DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke (Method.java:568)
    at org.apache.maven.wrapper.BootstrapMainStarter.start (BootstrapMainStarter.java:39)
    at org.apache.maven.wrapper.WrapperExecutor.execute (WrapperExecutor.java:122)
    at org.apache.maven.wrapper.MavenWrapperMain.main (MavenWrapperMain.java:61)
[ERROR] Error resolving #/components/parameters/meta-modified-from
java.net.URISyntaxException: Illegal character in opaque part at index 2: C:\dev\DairyNet\dairybox-icar-provider/../public-icar-api/src/main/resources/icar-v1/url-schemes/feedURLScheme.json
    at java.net.URI$Parser.fail (URI.java:2976)
    at java.net.URI$Parser.checkChars (URI.java:3147)
    at java.net.URI$Parser.parse (URI.java:3183)
    at java.net.URI.<init> (URI.java:623)

This is from feedUrlScheme as input.

[cookeac]

I investigated the problem @AndreasSchultzGEA identified. TL;DR: It is a tooling problem on Windows.

It seems it is caused by a problem in swagger-parser-v3 handling Windows path names that are passed to it by openapi-generator (v6.5 to v7.2). The actual problem is how openapi-generator passes the input file spec to the parser, but it shows up when swagger-parser-v3 is used to handle recent JSON Schema files (not just OpenAPI 3.1, but OpenAPI 3.1 implies that recent JSON Schema parsing is needed).

There are two workarounds in the discussion of the issue here: OpenAPITools/openapi-generator#15202

• Run it in a Linux container, as the problem is specific to Windows
• Use a Maven plugin to quote the double-quote symbols in the input spec.