3

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/

CTC
  • 451
  • 1
  • 8
  • 20

1 Answers1

3

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.

Vincenzo
  • 1,549
  • 1
  • 9
  • 17
  • Good idea, thanks @Vincenzo. I did chat with the apiary team last week, and they said they have a feature in beta that will allow for Data Structures to be inserted into the markup of the documentation, not just in the typical request/response places, so that will also help. – CTC Jun 15 '16 at 15:14
  • Good. You might want to track the [component](https://github.com/apiaryio/attributes-kit) which makes this happen. – Vincenzo Jun 15 '16 at 20:05
  • UPDATE from 2021: moviedb are no longer using apiary. attributes-kit component has been deprecated. – mrded Jan 21 '21 at 12:25