4 ms·

What most API documentation lacks is one thing. Examples. Real, working, copy-n-paste examples. While I prefer the swagger format, we use Blueprint at work b

What most API documentation lacks is one thing. 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.

porpoisemonkey 11y ago
There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0 https://github.com/OAI/OpenAPI-Specification/tree/master/exa...
- palakchokshi 11y ago
  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.
  - porpoisemonkey 11y ago
    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/swagger-codegen/ http://swagger.io/getting-started/ http://swagger.io/getting-started/
- whatnotests 11y ago
  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.
  - progx 11y ago
    You mean something like this: http://apidocjs.com/example/ http://apidocjs.com/example/ generated from this https://github.com/apidoc/apidocjs.com/tree/gh-pages/source/example https://github.com/apidoc/apidocjs.com/tree/gh-pages/source/...
    - whatnotests 11y ago
      Very nice! I particularly like the ability to compare two different versions visually.
bbrennan 11y ago
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

porpoisemonkey 11y ago

There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0 https://github.com/OAI/OpenAPI-Specification/tree/master/exa...

palakchokshi 11y ago
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.
- porpoisemonkey 11y ago
  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/swagger-codegen/ http://swagger.io/getting-started/ http://swagger.io/getting-started/
whatnotests 11y ago
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.
- progx 11y ago
  You mean something like this: http://apidocjs.com/example/ http://apidocjs.com/example/ generated from this https://github.com/apidoc/apidocjs.com/tree/gh-pages/source/example https://github.com/apidoc/apidocjs.com/tree/gh-pages/source/...
  - whatnotests 11y ago
    Very nice! I particularly like the ability to compare two different versions visually.

bbrennan 11y ago

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