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
Re:The Open API Initiative
by porpoisemonkey on Friday March 11, 2016 @05:59PM
(#11270163)
There does appear to be an examples section in the project repository
https://github.com/OAI/OpenAPI-Specification/tree/master/exa...
Re:The Open API Initiative
by palakchokshi on Friday March 11, 2016 @06:48PM
(#11270455)
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.
Re:The Open API Initiative
by porpoisemonkey on Friday March 11, 2016 @07:26PM
(#11270606)
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.
Re:The Open API Initiative
by whatnotests on Saturday March 12, 2016 @01:08AM
(#11271604)
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:
generated from this
https://github.com/apidoc/apidocjs.com/tree/gh-pages/source/...
Re:The Open API Initiative
by whatnotests on Saturday March 12, 2016 @05:44PM
(#11275048)
Very nice! I particularly like the ability to compare two different versions visually.
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.