Downgrade to Openapi v3.0.3 for better tooling support

[joodie]

Current tooling & libraries generally do not yet support openapi
3.1.0. For instance, none of the data validation libraries at
https://openapi.tools/#data-validators supports it. 3.0.3 support is
widespread.

This change sets the version to 3.0.3 and fixes an issue with the
default values for the sort parameter, which should be an array, so
its default should also be an array.

Further consequences: the duration format is not explicitly
supported in 3.0.3, so strictly conforming validators will allow any
string value for duration fields. This patch replaces the duration
format with an explicit pattern matching the ISO8601 duration format.

[hamrt]

Waarom zijn de voorbeelden in de vorm van een array? Volgens mij zou het één van de waarden uit de lijst moeten zijn. Als het nodig is voor tooling om naar 3.0.3 te gaan lijkt me de oplossing die voorgesteld wordt voor duration prima

[jelmerderonde]

@hamrt die arrays kloppen technisch gezien wel, maar het rendert alleen niet heel lekker in de documentatie. We speccen desort parameter als een array of strings, want clients mogen meerdere velden opgeven om op te sorteren. Omdat het een query parameter is zou dat met komma's gaan: ?sort=name,-date. De default waarde is dan ook een array met één sort parameter. Jammer genoeg rendert redoc dat als ["startDate"]

[joodie]

@jelmerderonde ik weet niet zeker of het correct is om bij een array een enkele scalar value als default te hebben, de spec zegt:

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject

default - The default value represents what would be assumed by the consumer of the input
as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST
conform to the defined type for the Schema Object defined at the same level. For example,
if type is string, then default can be "foo" but cannot be 1.

De de library die wij gebruiken accepteert ook geen scalar defaults voor array waarden.

Voor de duidelijkheid: het gaat hier om arrays van enums.

[joodie]

Wat betreft redoc rendering, misschien werkt het mooier als we ipv:

default: [ foo ]

DIt doen:

   default:
      - foo

[jelmerderonde]

@joodie net geprobeerd, helaas rendert dat op dezelfde manier:

[jelmerderonde]

Dit lijkt het issue te zijn in Redoc: Redocly/redoc#1806

Staat al open sinds 26 nov 2021, maar lijkt dus nog niet gefixt te zijn.

Mijn voorstel: wel deze PR mergen als dat nodig is voor compatibiliteit met 3.0.3 tooling. Eventueel kunnen we wel wel een example toevoegen om het duidelijker te maken, dat rendert wel goed:

issue was resolved