September 08, 2014

Posted by Sherri Flemings | File under : , , ,
I just discovered this nifty little tool to generate the API docs for Stitchcrafter. It's called apiDoc, and I had it integrated into my grunt build in a few minutes. 30 minutes later, I had my existing docblocks converted to the custom @api tags, and now I have a nice looking document for my API.
Screenshot of my first API document using the default template
There are a few issues I've noticed, but they're only minor, and compared to other tools I've tried in this category it has the best out-of-the-box results so far. I may end up forking this to address these issues and help keep this project awesome :)

My favourite bits:

  • very easy to integrate into any project 
  • the version compare feature
  • modern clean look as the default template
  • open source with the ability to create your own custom tag parsers
Response examples are automatically grouped into a tabbed pane with the default template.


Minor Issues:

  • It assumes error messages are 4XX (I may be able to fix this with a custom template)
  • I'd like to automate the endpoint versioning, I don't like the idea of always having to manually add/update the version with each code update. (This is something I may be able to set up using the grunt preprocess task though)
  • The ability to easily add documentation that isn't for an endpoint. Since all my error objects are the same shape, I wanted to group them under an 'Errors' heading. I managed to fudge it for now using the @api tags, but the template tries to format it as if it had a url endpoint. I think I can probably just create my own parser for this as well.

I haven't spent much time using it yet, but I think this is my new goto API generator. You can dig into it here:
Happy documenting :)
Reactions:

0 comments:

Post a Comment