API Description Documents and Parse Results for Integration Testing

[kylef]

Right now we provide swagger-zoo as a package with common Swagger 2 document and their API Elements parse result. We should bring -zoo or similiar packages for each API Description format we support (API Blueprint, OpenAPI 2, OpenAPI 3). This makes it easier for other integrators to provide them with test documents, Dredd is making use of swagger-zoo. API Blueprint equivilent should likely include all of the test fixtures from Drafter.

Once this is complete, we can simplify our own testing strategy in our parsing service as we can make our tests use the zoo fixtures. When we update the parser we will update to the matching zoo and then all of the integration tests would be against API Elements from the same parser version. Right now it can be cumbersome as updating the parser can break some of the integration tests and requires digging through them and updating them (sometimes across multiple repos).

Secondly, I think we should share the "Polls API" examples we produced in these zoo packages along with their API Element parse results. This means that Apiary can take these examples directly from the package and it can utilise the API Elements Parse Result for its own example generation. I know right now that Apiary includes versions of the parser to generate these examples parse results during deploy. This generation could be updated to use these new -zoo like Polls API fixture parse result so that Apiary doesn't need to depend on these parser adapters which I believe can speed up npm install time by a few minutes if it no longer needs to depend on the parsers.

We could take into account #32 and #34 regarding naming. Since these zoo packages specifically contain API Elements, perhaps they should be branded like such @apielements/openapi2-examples etc.

/cc @honzajavorek for any feedback from swagger-zoo for API Blueprint equivilent package
/cc @freaz Let me know your thoughs on the last part of this regarding Apiary examples.

[honzajavorek]

I like the whole idea. My only comment would be that mson-zoo exists to test the "Attributes Kit". Do we want to adopt it into the API Elements package as well or is it a different can of worms?