Bugfix/280/path item references

Closes https://github.com/mattpolzin/OpenAPIKit/issues/280

Todo:

[x] Add support to the OpenAPIKit module (supports PathItem references in the Components Object)
[x] Add support to the OpenAPIKit30 module (does not support PathItem references in the Components Object)
[x] Add net-new tests that cover encode/decoding path item references.
[x] Add new error reporting tests for when a path is neither a reference nor a path item.
[x] Double check that code changes in response to new structure make sense -- for example, does code that used to be able to loop over all path items without looking them up in the Components now want to loop over all accessible items ignoring the rest or throw an exception if a path item that cannot be looked up is encountered? What's the most backwards-compatible or ergonomic answer in each case? Add new functions to facilitate either?
[x] Add default-enabled builtin validation that PathItem references are valid.
[x] write up release notes that lay out breaking changes.

Release Notes

This release fixes #280 by allowing Path Items to be references as well as inlined Path Item Objects. This applies to both the OpenAPIKit30 (OpenAPI 3.0.x) and OpenAPIKit (OpenAPI 3.1.x) modules. However, OpenAPI 3.0.x did not allow Path Item Objects to be stored in the Components Object whereas OpenAPI 3.1.x does, so only external JSON References to Path Item Objects are meaningful when working with OpenAPI 3.0.x.

Noteworthy Differences

OpenAPI.Document helpers that collect information not stored directly in the document now skip over external JSON References to Path Item Objects. The use of these helpers is the same, but the distinction between internal and external references to Path Item Objects is important here (where before references to Path Item Objects were simply not expressible with OpenAPIKit). These helpers are var routes: [Route], var allOperationIds: [String], var allServers: [OpenAPI.Server], and var allTags: Set<String>.
Because the path to anything in a Document that exists as part of a Path Item Object or its children is now potentially behind a JSON Reference, the error messages for improperly formatted Documents have changed in some cases. They still reflect the same underlying problems, but the verbiage has changed.
It is now possible to write reference entries to Path Item Objects into the Paths dictionary: paths: [ "/hello": .reference(.component(named: "path1")) ]. This internal reference to the Components Object would only be valid for OpenAPI 3.1.x; External references like the following are valid for OpenAPI 3.0.x as well as 3.1.x: paths: [ "/hello": .reference(.external(URL(string: "https://website.com/hi")!)) ]

Breaking Changes

Constructing an entry in the Document.paths dictionary now requires specifying Either a JSON Reference to a Path Item Object or the Path Item Object itself -- this means that where you used to write something like:

paths: [
  "/hello/world": OpenAPI.PathItem(description: "hi", ...)
]

You will now need to wrap it in an Either constructor like:

paths: [
  "/hello/world": .pathItem(OpenAPI.PathItem(description: "hi", ...))
]

There is also a convenience initializer for Either in this context which means that you can also write:

paths: [
  "/hello/world": .init(description: "hi", ...)
]

You may already have been using the .init shorthand to construct OpenAPI.PathItems in which case your code does not need to change.

Accessing an entry in the Document.paths dictionary now requires digging into an Either that may be a JSON Reference or a Path Item Object -- this means that where you used to write something like:

let pathItem = document.paths["hello/world"]

You will now need to decide between the following:

// access the path item (ignoring the possibility that it could be a reference)
let pathItemObject = document.paths["hello/world"]?.pathItemValue

// access the reference directly (ignoring the possibility that it could be a path item object):
let pathItemReference = document.paths["hello/world"]?.reference

// look the path item up in the Components Object (OpenAPIKit module only because this requires OpenAPI 3.1.x):
let pathItem = document.paths["hello/world"].flatMap { document.components[$0] }

// switch on the Either and handle it differently depending on the result:
switch document.paths["hello/world"] {
  case .a(let reference):
    break
  case .b(let pathItem):
    break
  case nil:
    break
}

NOTE: The error you will get in places where you need to make the above adjustments will look like:

Cannot convert value of type 'OpenAPI.PathItem' to expected dictionary value type 'Either<JSONReference<OpenAPI.PathItem>, OpenAPI.PathItem>'

mattpolzin / OpenAPIKit