README

Important note

This project is currently not active maintained!
See discussion https://github.com/apidoc/apidoc/issues/1436

 apiDoc

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

!validate



 Documentation: apidocjs.com

 Live DEMO

 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


 Programmatic usage

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
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):

   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 p