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