@cdcabrera/apidoc

apiDoc

apiDoc creates documentation from API descriptions in your source code.

Important note

For the foreseeable future, ONLY maintaining the project build. Anything beyond general maintenance, currently, falls outside the intended scope.

NPM released under @cdcabrera/apidoc

Having options for handling specs is good, especially an easy-to-implement open/free alternative.

The focus of this maintenance will be dependency updates and NodeJS compatibility on the main apidoc package. May continue refactoring aspects of the codebase and consolidating, but then again no promises.

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

Documentation: apidocjs.com

Live DEMO

Installation

$ npm install -g @cdcabrera/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

Programmatic usage

You can generate the documentation programmatically:

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

$ npm install -D @types/apidoc

Container image

You can use apidoc in Podman or Docker.

We recommend using Podman Desktop these days.

• https://podman-desktop.io/downloads

Podman

# first build the image after cloning this repository
podman build -t apidoc/apidoc .
# run it
podman run --rm -v $(pwd):/home/node/apidoc apidoc/apidoc -o YOUR_OUTPUT_DIRECTORY -i YOUR_INPUT_DIRECTORY

Docker

# 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 YOUR_OUTPUT_DIRECTORY -i YOUR_INPUT_DIRECTORY

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.
  #*
  

  =pod
  This is a comment.
  =cut
  

• Python

  """
  This is a comment.
  """
  

• 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