I'm just starting with api blueprint, using apiary to generate the docs for our api. We have both a REST api and a number of webhooks. The REST api is easy enough to create, but I can't figure out how best to generate the documentation for the webhooks.
We'd like to share Data Structures between our webhooks and our REST api.
So far, the only thing I can think of is to document the webhooks just like a REST resource. That feels a little strange, since usually webhook documentation is just payload information, but perhaps that's the best option.
Anyone do this? Or perhaps there are better tools out there for this?
Ultimately would love something like what github does: https://developer.github.com/webhooks/
Even if APIBlueprint does not have any built-in construct to document a webhook, keep in mind that you can always use markdown to describe your end points.
With that "power", you should be able to express all your thoughts.
If you have a look to MovieDb Api, you can see how they are using markdown tables to express stuff that probably does not really fit with ApiBlueprint language itself.
I hope this helps!
V.