andrdru/apidoc repository overview

⁠apiDoc

Generates a RESTful web API Documentation.

Changes from previous version visit CHANGELOG.md⁠

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

Documentation at apidocjs.com⁠ or as Docset⁠.

Example⁠ output.

⁠HELP NEEDED! Search for a Developer

Because of my limited time i need one or more devs that could build and maintain a "Send Sample Request Plugin".

The Plugin should be loose coupled to the template, so it should be a separate project. This Plugin should send example data to an API-Endpoint and process the response. Supported formats should be JSON, XML, whatever.

Many issues belong to the current (unmaintained) plugin, (Milestone: Send Sample Request Plugin)(https://github.com/apidoc/apidoc/milestone/4⁠) If you want ot work on this, please send me a PM.

⁠Installation

$ npm install apidoc -g

⁠Alternative docker install

$ docker pull apidoc/apidoc

Then you will need to mount your file storage -v '<apidoc.json dir>:/apidoc' to docker container.

Example:

$ docker run --rm -v '$(PWD):/apidoc' -it apidoc/apidoc \
    --input ./example \
    --output ./docker-example \
    -v

Creates from input files in example/ a documentation in path docker-example/.

⁠Changelog

CHANGELOG.md⁠

⁠Example

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

$ apidoc -i example/ -o doc/

Creates from input files in example/ a documentation in path doc/.

More examples and best practice hints: EXAMPLES.md⁠

⁠Supported programming languages

• C#, Go, Dart, Java, JavaScript, PHP, Scala (all DocStyle capable languages):

  /**
    * This is a comment.
    */
  

  Copy

• Clojure:

  ;;;;
  ;; This is a comment.
  ;;;;
  

  Copy

• CoffeeScript:

  ###
  This is a comment.
  ###
  

  Copy

• Erlang:

  %{
  This is a comment.
  %}
  

  Copy

• Perl

  #**
  # This is a comment.
  #*
  

  Copy

  =pod
  This is a comment.
  =cut
  

  Copy

• Python

  """
  This is a comment.
  """
  

  Copy

• Ruby

  =begin
  This is a comment.
  =end
  

  Copy

⁠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

⁠Build tools

• flask-apidoc⁠ pip install flask-apidoc
• grunt-apidoc⁠ npm install grunt-apidoc.
• gapidoc (gulp)⁠ npm install gapidoc.
• gulp-apidoc⁠ npm install gulp-apidoc.
• gulp-apidocjs⁠ npm install gulp-apidocjs.

⁠Integration

• Eclipse Java apiDoc editor templates⁠
• Eclipse plugin⁠
• Microsoft WebAPI⁠
• Sublime Text plugin⁠

⁠Converter

• apidoc-swagger⁠
• gulp-apidoc-swagger⁠
• Docmaster⁠

⁠FAQ

• Filter for public / private API⁠

⁠Extend apiDoc and write your own Plugin

For details and an example view apidoc-plugin-test⁠

⁠Help

Please add issues⁠ if you have a question or found a problem. Pull requests are welcome too!

A chat about apiDoc is on Gitter⁠.