Support for OpenAPI 3.0

[JordiPolo]

These are the changes:
https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/

[softprops]

Good idea. Ill look into this after settling on type interfaces for version 2

[nbigaouette]

I'm exploring OpenAPI v3 for some project, and decided to try to implement the spec.

It's not complete (it's missing many objects from the spec) but I think it's in a working state. I can deserialize and serialize back to yml a "small" API (<250 lines) with almost no loss, mostly formatting (quotes or not around strings, a --- at the top of the file, fields ordering, etc.).

I wrote a small dumb bash script to check which objects are missing an struct by comparing with the table of content of the spec. Here's the output:

./find_missing_objects.sh
OpenAPI NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oasObject
Server Variable NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#serverVariableObject
Components NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#componentsObject
Paths NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#pathsObject
External Documentation NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#externalDocumentationObject
Responses NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#responsesObject
Link NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#linkObject
Reference NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#referenceObject
Discriminator NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#discriminatorObject
XML NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#xmlObject
Security Scheme NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securitySchemeObject
OAuth Flows NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oauthFlowsObject
OAuth Flow NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#oauthFlowObject
Security Requirement NOT implemented! See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#securityRequirementObject

I'm not sure how to test/validate the code though. The only test in the original crate is a deserialization test on the couple of OpenAPI v3 examples. As with my manual validation above, re-serialization can't really be used to compare with original since ordering and quoting can change. I guess the reference yml files could be split into smaller chunks to test specific structs...

I would like to add proper referencing (#12) but for now I use strings.

I also have a small check for the API version (#8), but it can only be checked after deserialization. So if one tries to deserialize an unsupported version, it will fail at the deserialization step, not the at the validation.

I haven't forked this repo (started a new one instead, not even on github). I though it was easier to start from scratch and add what was required for v3, importing from this repo when it was making sense. As such it could probably be merged back into this repo.

Let me know if it could be useful!

[nbigaouette]

I've actually found a way to solve both the field ordering issue and validating that features are implemented.

For this, I do both of these conversions:

1. File -> String -> serde_yaml::Value -> serde_json::Value -> String (using serde_json::to_string_pretty)
2. File -> Spec -> serde_json::Value -> String (using serde_json::to_string_pretty)
   and compare the result. Fields will have the same ordering (the one dictated by serde_json).

Also, missing features will clearly be shown as missing fields in the second string above.