Phase out OpenAPI 2.0

[pvdbosch]

Because the REST guide and the reusable OpenAPI documents mostly seem to be used for new APIs or major new revisions that use OpenAPI 3, we could consider phasing out OpenAPI 2.0.

• could we start phasing out now or still too early?
• maybe keep the last version of the guide supporting OpenAPI 2.0 around on another URL, linked for the 'main' version?
• can 2.0-support be dropped inside new minor versions of the belgif OpenAPI artifacts? (previous releases are still available)
• is it OK for the styleguide validator to also drop support?

Advantages would be:

• simplify the guide with sections that illustrate both OpenAPI versions
• don't need to maintain all belgif openapi documents in duplicate (often forgotten to update Swagger)
• less confusion for users which example or belgif schema to look at
• don't need to test styleguide validator on OpenAPI 2.0 and implement OpenAPI 2.0 workarounds

[pvdbosch]

WG agrees to drop OpenAPI 2.0 support:

• remove sections in REST guide, include warning (don't refer to outdated version)
• rest-guide-validator: create 3.0 version , print warning "validator doesn't support 2.0" but let it complete with "OK" exit code
• for openapi schemas: remove from source code; only increment minor; mention it in release notes
• rest-problem-java: no impact

[jpraet]

rest-guide-validator: create 3.0 version , print warning "validator doesn't support 2.0" but let it complete with "OK" exit code

I assume the https://www.belgif.be/specification/rest/api-guide/#rule-oas-contra rule will be updated to require OpenAPI 3.0? So a Swagger 2.0 contract is not compliant with the REST guide. I would therefore prefer that the rest-guide-validator raised a violation. Impacted Swagger 2.0 contracts can define an x-ignore-rules for oas-contra, or pin the validator version to 2.2.1, or migrate to OpenAPI 3.0. Only printing a warning seems too lenient in my opinion and will often go unnoticed.

for openapi schemas: remove from source code; only increment minor; mention it in release notes

https://github.com/belgif/workflows/blob/main/.github/workflows/openapi-release-workflow.yml will also need updating.

[pvdbosch]

I assume the https://www.belgif.be/specification/rest/api-guide/#rule-oas-contra rule will be updated to require OpenAPI 3.0?

I'll propose something like "new APIs should use OpenAPI 3.0".

So a Swagger 2.0 contract is not compliant with the REST guide. I would therefore prefer that the rest-guide-validator raised a violation. Impacted Swagger 2.0 contracts can define an x-ignore-rules for oas-contra, or pin the validator version to 2.2.1, or migrate to OpenAPI 3.0. Only printing a warning seems too lenient in my opinion and will often go unnoticed.

I'll bring it up in next WG bc that's different from what was discussed in the WG. Existing OpenAPI 2 applications often only will upgrade for a new major release, but that's also the case for many other new (stricter) rules that are backwards-incompatible.

In #52, we'll have to check feasibility to implement this as a rule in the validator, because we want to stop after parsing before other rules are being executed while rules are normally independent.

[jpraet]

OpenAPI 2.0 removed from all openapi-* modules

[pvdbosch]

rest-guide-validator: WG prefers to make configurable to fail on OpenAPI 2.0 fail, default is then to fail. Configurable with skipOnError.