apiDoc

apiDoc creates a documentation from API descriptions in your source code.

!validate

$3

$3

Installation

``bash
$ npm install -g apidoc
`

Usage

Add some apidoc comments anywhere in your source code:

`java
/**
* @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/.

`bash
$ 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).

`bash
$ git clone https://github.com/apidoc/apidoc && cd apidoc
$ npm install --prod
$ ./bin/apidoc -i example -o /tmp/doc
$ $BROWSER /tmp/doc
`

$3

You can generate the documentation programmatically:

`ts
import path from 'path'
import { createDoc } from 'apidoc'

const doc = createDoc({
src: path.resolve(__dirname, 'src'),
dest: path.resolve(__dirname, 'doc'), // can be omitted if dryRun is true
// if you don't want to generate the output files:
dryRun: true,
// if you don't want to see any log output:
silent: true,
})

if (typeof doc !== 'boolean') {
// Documentation was generated!
console.log(doc.data) // the parsed api documentation object
console.log(doc.project) // the project information
}
`

Install type definitions (see @types/apidoc):

`bash
$ npm install -D @types/apidoc
`

Docker image

You can use apidoc in Docker like this:

~~~bash


first build the image after cloning this repository

`javascript
/**
* This is a comment.
*/
`

* Clojure:

`clojure
;;;;
;; This is a comment.
;;;;
`

* CoffeeScript:

`coffeescript
###
This is a comment.
###
`

* Elixir:

`elixir
#{
# This is a comment.
#}
`

* Erlang:

`erlang
%{
% This is a comment.
%}
`

* Perl

`perl
#**
# This is a comment.
#*
`

`perl
=pod
This is a comment.
=cut
`

* Python

`python
"""
This is a comment.
"""
`

* Ruby

`ruby
=begin
This 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.

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`.

Integration

* Eclipse Java apiDoc editor templates
* Eclipse plugin
* Microsoft WebAPI
* Sublime Text plugin

Converter

* apidoc-swagger
* apidoc-swagger-3
* gulp-apidoc-swagger
* Docmaster
* apidoc-markdown