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.

http://swagger.io/swagger-codegen/

http://swagger.io/getting-started/

Yes, I mean documentation in general.

It's fine to just show a long list of method signatures and class hierarchies, but a working code sample is the picture that's worth a thousand words.

You mean something like this:

http://apidocjs.com/example/

generated from this

https://github.com/apidoc/apidocjs.com/tree/gh-pages/source/...

Very nice! I particularly like the ability to compare two different versions visually.