@cdcabrera/apidoc v2.0.2
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
apidocpackage. 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/apidocUsage
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/docProgrammatic 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/apidocContainer image
You can use apidoc in Podman or Docker.
We recommend using Podman Desktop these days.
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_DIRECTORYDocker
# 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_DIRECTORYSupported 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. =cutPython
""" 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.