wip: oas2 traverser & tests

[acunniffe]

Description - A few users have been asking about when OAS 2 support is coming. We were not sure how hard supporting multiple versions would be, but as we discovered when we released 3.1 support last month, the facts model effectively normalizes out the structure of the OpenAPI specifications.

The OAS 2 traverser will traverse the unique structure of these documents and map all of their types onto our standard facts. That mean OOTB our built-in rules will work. If a company has written custom rules that look at the raw values of different OpenAPI entities, those may break when encountering an unexpected spec version. That should be pretty rare. If you want to support both major versions, you need to update the custom rules anyway and that is not the worst way to find out you need to.

• replaces content contentType with produces and consumes
• replaces requestBody with the request parameter that has in: body
• removes nullable, oneOf, anyOf, allOf -- not supported in oas 2
• includes on some known limitations
  • omits formData and examples (these can come later if needed)
• adds OpenAPI v2 validation and semver parsing
• tests the facts produced by 3 OAS 2 specifications from Azure, & Petstore. Manually reviewed and snapshotted
  • looked for multiples of bodies for each produces and consumes
  • path parameters get generated properly
  • schema facts are correct

questions?

• All over our code we use ParseOpenAPIResult, and jsonLike is oas3 typed. That type here has never been correct. We say it is oas3, but there's no validation at this stage. The sourcemap parser will only fail if a $ref can't be resolved. It could be any data that is YAML and JSON. We have the validator, I propose that is where the typing gets applied. Ie validator would return `errors?: string[] , 3_0?: OpenAPI_V3, 3_1?: OpenAPI_V3_1, 2_0?: OpenAPI_V2_0
• Does the changelog or anything in Optic Cloud strongly expect the specs to be OpenAPI 3? What does the path to supporting OAS 2 look like in the changlog / cloud?
• What else could we write tests for?

current state?

• the validator is still set to fail on oas2, so we could merge these changes without the support being enabled
• traverser is working great. I can keep adding more tests.
• we can't turn it on until we address the ParseOpenAPIResult issue and do some retyping.
• we can't turn it on until we validate Changelog works OR decide not to support that to start
  • what if we choose not to upload oas2 to cloud / changelogs? That lets us give this to customers and validate interest in full story before going further, and takes pressure off the cloud team who have a lot of other things going on right now

[acunniffe]

Testable via npm -g install @useoptic/[email protected]

[niclim]

closing for now, we have a different approach we want to take to support oas2