While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation.
Sure, schema helps, but having a spot to just lay out an example request or response is really important.
Another thing: often, one must perform prerequisite steps before making a call to a given API method. Eg - you must have booked a flight before checking in. The context surrounding how an API fits into its use-cases is as important as the API itself.
Having a machine readable spec is important for driving examples though. For instance, at LucyBot we use OpenAPI to drive Recipes - tutorials for using an API to achieve a specific use case. Each recipe provides working sample code in a few different languages. You can see examples for Kaltura's video API at developer.kaltura.org
I believe he meant a way to put examples in the spec itself. I believe they have a client SDK that will consume the API spec and allow you to make requests and see responses.
Ah I see. The OpenAPI specification for the interface description language and the auto-generation tools are actually two separate entities so I'm not sure it would make sense that they put examples for a specific auto-generation tool in the official OpenAPI repository.
It seems like the best supported tool for generating client and server stubs is Swagger Codegen. Version 2.1.2 seems to support the OpenAPI 2.0 draft spec.
Examples.
Real, working, copy-n-paste examples.
While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation.
Sure, schema helps, but having a spot to just lay out an example request or response is really important.
Another thing: often, one must perform prerequisite steps before making a call to a given API method. Eg - you must have booked a flight before checking in. The context surrounding how an API fits into its use-cases is as important as the API itself.