Improve swagger/openapi specs and schemas

[RickMoynihan]

I’ve been using martian with drafter and I think drafters swagger schema could use some work to help improve openapi clients interop with it.

We should carefully consider backward compatibility, but there are some issues with the schemas. Many of them could be more much more precise, some are essentially set to “Any”; which blows the ability for martian.test to generate property based data from the schema specs.

Some crude experiments can be found here.

Areas for exploration and consideration

As a pre-requisite to the above the drafter martian client in that project could be ported into drafter, and cleaned up a little. This client has some advantages over the current one:

1. It uses martian/openapi data directly, and uses martian as the interface to drafter. Where as the existing client hides martian by wrapping it behind its own functions.
   • This makes it harder to extend
   • It's harder to use the machinery martian exposes for example based testing, vcr's, and also deriving property based tests from the swagger specs.
   • A martain based client will not need regenerating as drafters API itself evolves, as most of the improvements will be driven by the schemas evolution.
2. Once this client is in place, we could use it develop and iterate the swagger schema itself. Additionally we may want to use it to drive developments into martian, martian.test and the underlying schema-generator library. e.g. my experiments above showed that martian was lacking this feature. This is important because currently the swagger spec forms our contract with the outside world; but we don't really test it at the schema level itself; so it's difficult to know how good/usable our schema is for other clients.
3. Finally we can consider deprecating the existing client
4. Similarly we should probably make similar changes to the swirrl/auth0 library.