# apidoc

> RESTful web API Documentation Generator

Latest version **1.2.0** (published 2023-08-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install apidoc
pnpm add apidoc
yarn add apidoc
bun add apidoc
```

Provides the command `apidoc`.

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2023-08-23 |
| First published | 2013-04-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/apidoc) |
| Module format | CommonJS |
| Node | >=16.0.0 |
| Dependencies | 20 |
| Unpacked size | 543.3 KB |
| Known vulnerabilities | 0 (+3 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 9653 |
| Author | Peter Rottmann |
| Maintainers | apidoc |
| Keywords | api, apidoc, doc, documentation, rest, restful |

## Links

- npm: https://www.npmjs.com/package/apidoc
- Repository: https://github.com/apidoc/apidoc
- Homepage: https://apidocjs.com
- Issues: https://github.com/apidoc/apidoc/issues
- npm.io page: https://npm.io/package/apidoc

## Dependencies (20)

- [glob](https://npm.io/package/glob.md) ^7.2.0
- [jquery](https://npm.io/package/jquery.md) ^3.6.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [semver](https://npm.io/package/semver.md) ^7.5.0
- [nodemon](https://npm.io/package/nodemon.md) ^3.0.1
- [prismjs](https://npm.io/package/prismjs.md) ^1.25.0
- [webpack](https://npm.io/package/webpack.md) ^5.64.2
- [winston](https://npm.io/package/winston.md) ^3.3.3
- [fs-extra](https://npm.io/package/fs-extra.md) ^11.0.0
- [bootstrap](https://npm.io/package/bootstrap.md) 3.4.1
- [commander](https://npm.io/package/commander.md) ^10.0.0
- [klaw-sync](https://npm.io/package/klaw-sync.md) ^6.0.0
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.7
- [iconv-lite](https://npm.io/package/iconv-lite.md) ^0.6.3
- [markdown-it](https://npm.io/package/markdown-it.md) ^12.2.0
- [webpack-cli](https://npm.io/package/webpack-cli.md) ^4.9.1
- [style-loader](https://npm.io/package/style-loader.md) ^3.3.1
- [expose-loader](https://npm.io/package/expose-loader.md) ^4.0.0
- [esbuild-loader](https://npm.io/package/esbuild-loader.md) ^2.16.0
- [diff-match-patch](https://npm.io/package/diff-match-patch.md) ^1.0.5

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2023-08-23
- 1.1.0 — 2023-07-14
- 1.0.3 — 2023-06-01
- 1.0.2 — 2023-04-30
- 1.0.1 — 2023-04-26
- 0.55.0 — 2023-04-26
- 0.54.0 — 2023-02-10
- 0.53.1 — 2022-10-17
- 0.53.0 — 2022-09-06
- 0.52.0 — 2022-07-17
- 0.51.1 — 2022-04-15
- 0.51.0 — 2022-03-21
- 0.50.5 — 2022-03-10
- 0.50.4 — 2022-02-02
- 0.50.3 — 2021-12-24
- … 81 more at https://npm.io/package/apidoc/versions

## README

# apiDoc

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

![validate](https://github.com/apidoc/apidoc/workflows/validate/badge.svg)
[![NPM version](https://badge.fury.io/js/apidoc.svg)](http://badge.fury.io/js/apidoc)
[![Join the chat at https://gitter.im/apidoc/talk](https://badges.gitter.im/apidoc/talk.svg)](https://gitter.im/apidoc/talk?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

### Documentation: [apidocjs.com](http://apidocjs.com)

### [Live DEMO](http://apidocjs.com/example/)

## 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](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/apidoc/index.d.ts)):

```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](https://github.com/willfarrell/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](https://github.com/apidoc/apidoc-plugin-test).

## Support

Please [create a new issue](https://github.com/apidoc/apidoc/issues/new/choose) 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](https://github.com/apidoc/apidoc/blob/master/CONTRIBUTING.md) file.

## Build tools

* [flask-apidoc](https://pypi.python.org/pypi/flask-apidoc/) `pip install flask-apidoc`
* [grunt-apidoc](https://github.com/apidoc/grunt-apidoc) `npm install grunt-apidoc`.
* [gapidoc (gulp)](https://github.com/techgaun/gulp-apidoc) `npm install gapidoc`.
* [webpack-apidoc](https://github.com/c0b41/webpack-apidoc) `npm install --save-dev webpack-apidoc`.

## Integration

* [Eclipse Java apiDoc editor templates](https://github.com/skhani/eclipse_java_apiDoc_templates)
* [Eclipse plugin](https://github.com/DWand/eclipse_pdt_apiDoc_editor_templates)
* [Microsoft WebAPI](https://github.com/chehabz/grunt-edge-apidoc-webapi-generator)
* [Sublime Text plugin](https://github.com/DWand/ST3_apiDocAutocompletion)

## Converter

* [apidoc-swagger](https://github.com/fsbahman/apidoc-swagger)
* [apidoc-swagger-3](https://github.com/amanoooo/apidoc-swagger-3)
* [gulp-apidoc-swagger](https://github.com/fsbahman/gulp-apidoc-swagger)
* [Docmaster](https://github.com/bonzzy/docmaster)
* [apidoc-markdown](https://github.com/rigwild/apidoc-markdown)

---
_Source: https://npm.io/package/apidoc · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._