apidoc

v1.2.0

Published

a year ago

RESTful web API Documentation Generator

Downloads

352,831

0High
0Medium
0Low

apidoc

api apidoc doc documentation rest restful

apiDoc

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

Documentation: apidocjs.com

Live DEMO

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

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

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme