apiDoc - Part 1 Introduction - RESTful web API Documentation

#documentation

#open source

#api

#restful

As the developer of apiDoc apidocjs.com - a documentation tool for RESTful web APIs - i want to introduce my project with some smaller articles.

apiDoc is OpenSource and can be forked at github.com/apidoc/apidoc. Critic, replies, issues and enhancements are welcome!

apiDoc uses node / npm with default for JavaScript-Files, but it can document any other language too.

Why apiDoc ?

The problem

We work in a small team and different programmers develop Frontend and Backend at the same time. That's why we need a system to document the backend interface.

First we start with external Tools, the problem was, when you develop and change things, you "forget" to update the docs, because you have to open the tool and search where to change the content.

Then we use a simple Textfiles (markdown), but formatting e.g. tables cost too much time, that's why we change to a simple Word-File. But the problem was the same, when you change the code, you have to change the documentation in an external file. And with many developer you have different formatting styles, different files, ...

Javadoc

I personally liked the Javadoc (phpdoc, jsdoc) document style and thought "why this style is not available for a RESTful API?"

Then i start searching and look and ask how others document their API. It exist many tools for testing an API or SaaS online tools for documentation, but they not solve the Problem how the content come from my code into the tool (they solve only parts of our "Word-File" Problem).

While we develop our own project teamspir.it i feel more and more the need for a solution like JSDoc.

Q&D

Finally i start developing apiDoc, i must admit: it was quick & dirty, i needed that tool but i did not have so much time, because of the development of our own application.
So don't shoot me for errors or not soooo nice code ;-) i try to fix it quickly if something is really wrong.