apiDoc
apiDoc creates a documentation from API descriptions in your source code.
Documentation: apidocjs.com
Example output.
Installation
$ npm install -g apidoc
Usage
Add some apidoc comments anywhere in your source code:
/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id User's unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */
Now generate the documentation from src/
into doc/
.
$ apidoc -i src/ -o doc/
This repository contains and example
folder from which you can generate a very complete documentation on an example api endpoint. It also contains best practice hints (in the footer.md
file).
$ git clone https://github.com/apidoc/apidoc && cd apidoc$ npm install --prod$ ./bin/apidoc -i example -o /tmp/doc$ $BROWSER /tmp/doc
Docker image
You can use apidoc in Docker like this:
# first build the image after cloning this repository docker build -t apidoc/apidoc .# run it docker run --rm -v $(pwd):/home/node/apidoc apidoc/apidoc -o outputdir -i inputdir
Supported programming languages
-
C#, Go, Dart, Java, JavaScript, PHP, Scala (all DocStyle capable languages):
/*** This is a comment.*/ -
Clojure:
;;;;;; This is a comment.;;;; -
CoffeeScript:
###This is a comment.### -
Elixir:
#{# This is a comment.#} -
Erlang:
%{% This is a comment.%} -
Perl
#**# This is a comment.#*=podThis is a comment.=cut -
Python
"""This is a comment.""" -
Ruby
=beginThis is a comment.=end
Plugins (extend apiDoc)
apiDoc will auto include installed plugins.
- apidoc-plugin-schema Generates and inject apidoc elements from api schemas.
npm install apidoc-plugin-schema
For details and an example on how to implement your own plugin, please view apidoc-plugin-test.
Support
Please create a new issue if you have a suggestion/question or if you found a problem/bug.
Contributing
apiDoc is a collaborative project. Pull requests are welcome. Please see the CONTRIBUTING file.
FAQ
Build tools
- flask-apidoc
pip install flask-apidoc
- grunt-apidoc
npm install grunt-apidoc
. - gapidoc (gulp)
npm install gapidoc
. - webpack-apidoc
npm install --save-dev webpack-apidoc
.