Support for external references

[daniel-chambers]

In an OpenAPI spec I'm trying to define, I need to be able to $ref out to Schemas defined in another OpenAPI contract. I'm trying to reuse some Schema types from another external contract without having to inline them into my contract. According to the OpenAPI spec (as far as I understand it), this is supported, since JSON References are URIs that can be absolute or relative and therefore can be pointed to an external file.

Unfortunately, openapi3 treats References like names to entities defined within the current OpenAPI contract. This is fine if all your entities are defined wholly within your own contract, but if you want to reference things externally, you can't.

An example external reference URI is: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/80c781e479f85ac67001ceb3e7e410e25d2a561b/schemas/v3.0/schema.json#/definitions/Schema (a reference to the schema of OpenAPI's Schema 😉)

This PR is an attempt to solve this by modifying the Reference newtype and changing it into a sum type:

data Reference 
  = InternalReference Text
  | ExternalReference URI

InternalReferences are handled with exactly the same behaviour as the old newtype Reference. ExternalReferences are basically treated opaquely and the URI within them in simply serialized/deserialized to JSON verbatim.

I'm not sure if this is necessarily the right approach to solve the problem, but I thought I'd submit it as food for thought and see what you thought about it. There are a couple of disadvantages:

• It's a big breaking change to the Reference type
• ExternalReferences are still kinda poorly supported, in that code that would have previously looked up a reference from a Definitions set, such as validation, just barfs on them. To fix this would require introducing IO to be able to load the external reference, and the ability to deserialize arbitrary JSON schema docs. However, one could argue that at least with this approach External References are somewhat supported, as opposed to right now, where they 100% don't work. 🤷‍♂️