Fix: #125. Support OAS 2.0.

[ioggstream]

This PR

• Fix Support (and reference) all OAS version from 2.0 #125
• supports OAS < 3.0
• clarifies that spec terminology refers to >=3.0
• delegate terminology to OAS documents and use generic terms (OAS resource, OAS document)
• minor tweaks from YAML editorial review.

[handrews]

Started looking at this- I need to think on the "OpenAPI Document" terminology as it really wasn't formalized until 3.0.4/3.1.1, but we actually streamlined the terminology somewhat in 3.2. I'll figure out what makes sense across the versions, which might tweak the text here and/or call for another PR (which I will submit if I think one is needed).

[handrews]

See #121 (comment) for some questions I'm trying to figure out which apply in part to this PR as well.

[ioggstream]

@handrews PTAL. Use generic terms. The goal for this PR is to support OAS2.0: if we agree, I'd say that for this scope, good enough is good enough.

Terminology can be deferred to an editorial review: WDYT?

[handrews]

@ioggstream I feel like there is a gap in understanding here, as the question of whether this applies to OpenAPI Documents or some broader "OpenAPI resource" concept is central to what we are discussing in PR #121, which at this point is re-opening the discussion from #110.

I would like to figure this out before accepted any PR, as it seems to all be the same thing.

In particular,it is really not clear to me what you think is different between "document" and "resource" other than perhaps the root Object type, which is the concern under discussion in #121. So I'm not willing to endorse "resource" without a clear understanding of the implications.

[handrews]

Terminology can be deferred to an editorial review: WDYT?

I think the terminology is the central concern here.

[ioggstream]

different between "document" and "resource"

See https://ietf-wg-httpapi.github.io/mediatypes/draft-ietf-httpapi-rest-api-mediatypes.html#section-1.1-2: the term "resource" is from HTTP.

The target of an HTTP request is called a "resource".

We use the term "resource" here because we do not know beforehand what will be the media type of its "representation":
it could be JSON, YAML, ... Client can only express its preference.

A resource can be represented using formats associated with different media types (e.g., application/json, application/yaml).

A "document" is whatever the associated OAS specification decides to be a document.
Since OAS terminology changes between versions (Document, Description, description, ...)
and may change in the future, this is something that should be probably be deferred to OAS.

OT: wrt the OpenAPI Object, I strongly suggest it should be the focus of other PRs, to avoid it to be a show-stopper for the publication.