Remove swagger: 2.0 from spec

The current OpenAPI spec has "swagger": "2.0" in it. Since it’s no longer called the swagger spec, this should go away.

I do believe we should continue to declare the version in the specification though, to make tooling more tolerant. Some points about that.

• One major issue with the Swagger 2.0 tooling was that it was looking for the “2.0” version in the spec itself. That meant, a “2.0.1” spec–even if structurally compatible–would not work. We should advise all tooling vendors as to versioning process and how they should detect versions inside the spec. Reference the concerns in #107. In a couple cases we probably should have bumped the spec version in 2.0 to 2.0.1, etc. Let’s not make that mistake again
• Declaring a semver approach for the spec makes sense. We don’t need to go too far into the details in this ticket as to what constitutes a major, minor, patch version, but in general, if we put a version in the next spec version (which I advocate), it should be in the x.y.z format.
• Making it “2.0” as a string vs. number was dumb. The above point solves that.

[IvanGoncharov]

@fehguy In that case, I suggest to change $schema: https://openapis.org/schemas/v3.0.0.json into $schema: https://openapis.org/version/v3.0.0/schemas/latest.json. In this case latest is alias for the lastest version of schema corresponding to OAI v3.0.0. But if you want to be precise you can set it to: $schema: https://openapis.org/version/v3.0.0/schemas/v1.0.1.json Which will point to v1.0.1 of the schema for OAI v3.0.0.

Aliasing isn’t a problem since Git support symlinks.

[fehguy]

Here is my proposal for addressing this.

Options:

• We can use the schema namespace instead of a OAI version
• We can use a oas attribute for the version

Pros:

• schema URL is more flexible.
• oas is more tooling friendly. Most tools cannot do much with a new version of the schema

Cons:

• schema url is very long. Useful for validation, not for interpretation
• oas as a numeric version has the same issue as swagger: "2.0"

Recommendation:

• use the oas specifier with semver semantics:

oas: 3.0.0-alpha

which will eventually be released as:

oas: 3.0.0

The multiple . will avoid the string/number issue from swagger: 2.0

• introduce an optional schema URL which can be used for validation. If absent, the tooling will choose the appropriate OAS schema.

• Tooling will be responsible for parsing with semver compatibilty:

  Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.
  • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format

example:

oas: 3.0.0
schema: https://openapis.org/schemas/v3.0.0.json