README.md

    Important note

    This project is currently not active maintained! See discussion https://github.com/apidoc/apidoc/issues/1436

    apiDoc

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

    validate NPM version Join the chat at https://gitter.im/apidoc/talk

    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

    Integration

    Converter

    Описание

    RESTful web API Documentation Generator.

    Конвейеры
    0 успешных
    0 с ошибкой