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