<p align="center"> <img src="./apidog.png" alt="ApiDog"> </p>

apiDog

apiDog is a API documentation generator alternative to the apiDoc.

Features:

• Templates for:
  • Minimalistic HTML file with dynamic assets loading
  • Single pre-compiled HTML file with no external dependencies
  • apidoc.apidoc text file
  • Markdown file
  • Swagger specification file (v2.0, v3.0)
• Server proxy
• Send sample request plugin for html template:
  • Transports support:
    • HTTP/HTTPS (via Server proxy only HTTP)
    • Nats PUB/SUB (via Server proxy)
    • Nats RPC (remote procedure call, via Server proxy)
    • RabbitMQ PUS/SUB (via Server proxy)
    • RabbitMQ RPC (remote procedure call, via Server proxy)
    • Redis PUB/SUB (via Server proxy)
    • Socket.IO
    • WebSocket/WebSocket Secure (W3C) (via Server proxy only WebSocket)
  • Content types support:
    • Form
    • JSON
    • XML
  • Nested typed params
  • Type variants
  • Presets (saved requests)
  • Variables

Table of contents

• Installation
• CLI
• Additional annotations
  • @apiChapter
  • @apiContentType
  • @apiDefine
  • @apiErrorPrefix
  • @apiErrorValue
  • @apiFamily
  • @apiHeaderValue
  • @apiNote
  • @apiParamPrefix
  • @apiParamValue
  • @apiSchema
  • @apiSampleRequestOption
  • @apiSampleRequestVariable
  • @apiSubgroup
  • @apiSuccessPrefix
  • @apiSuccessValue
  • @apiTag
  • @apiUse
• Built-in templates
  • @apidoc
  • @html (default)
  • @html.standalone
  • @md
  • @swagger.2.0
  • @swagger.3.0
• @html template "Send sample request" plug-in
  • Type variants

Installation

npm i @akaterra.co/apidog -g

CLI

apidog -h

Parameters:

• --description "description" - Custom description that will be used as a description of the generated documentation

  Default is [ package.json in input directory ].description or null by default.

• -i, --input "input directory" - Input source(-s) to be scanned for doc blocks

  Can be multiple. Default is current directory.

• --jsonschema "source" - JSON Schema source(-s) to be loaded for resolving the external references

  Can be multiple.

  apidog -i '@apiSchema {jsonschema=./schemas/my-schema.json#definitions.create} @apiParam' -o my-api/ --parser inline --jsonschema ./schemas/schema1.json --jsonschema ./schemas/schema2.json
  

• --ordered - Process titles as ordered titles

  Order index must be in format of "1.2.3." and must start the title. Titles will be sorted numerically by order index, then the order index will be removed.

• -o, --output "output directory" - Output directory where "apidoc.html" and additional files will be written

  Same as input directory by default.

• --parser "dir" | "inline" | "swagger" -- Parser to be used to parse the doc blocks sources

  Default is "dir".

  "dir" is used to scan the source files in the provided input directory for the doc blocks.

  apidog --parser dir
  

  "inline" is used to scan the input as lines of the doc block.

  apidog --parser inline -i "@api {get} /version"
  

  "swagger" is used to parse the provided Swagger specification sources.

  apidog --parser swagger -i ./api-v1.swagger.json -i ./api-v2.swagger.json
  

• -p, --private ["tag"] -- Tags to filter doc blocks having all the private tags or entirely marked as private

  Can be multiple. By default takes all the doc blocks.

• -s, --sampleRequestUrl, --sampleUrl - Base URL that will be used as a prefix for all relative api paths (of HTTP/HTTPS and WebSocket types) in sample requests

  Default is [ config.json in input directory ].sampleUrl

• --sampleRequestProxy[:http | :nats | :rabbitmq | :redisPub | :redisSub | :ws] - URL of apiDog proxy to be used to pass requests through it. "http", "nats", "rabbitmq", "redisPub", "redisSub" or "websocket" specifier provides a proxy for the specified transport

• -t, --template - Alias of the built-in template or the directory where the custom template be load from

  Default is "@html".

  Build-in templates:

  • @apidoc
  • @html
  • @html.standalone
  • @md
  • @swagger.2.0
  • @swagger.3.0

• --title - Custom title that will be used as a title of the generated documentation

  Default is [ package.json in input directory ].name, [ config.json in input directory ].title or "Untitled" by default

• --withSrp, --withSampleRequestProxy ["update"] - Create (not rewrites existing) also "apidog_proxy.js", "apidog_proxy.config.js" and "package.json" in the output directory

  If the above files already exist, they will not be rewritten. To rewrite files use --withSampleRequestProxy=update.

Additional annotations

@apiChapter

Format:

@apiChapter name

Defines chapter. Can be used to split doc blocks between multiple namespaces.

If @apiDefine declares definition with the same name also includes its title and description.

@apiContentType

Format:

@apiContentType contentType

Defines content type. Can be defined multiply.

Content type will be used as a filter of the @apiExample content having corresponding {type}. Also the data of the sample request will be formatted according to it. Currently supported data format of the sample request are FORM, JSON and XML.

@apiDefine

Format:

@apiDefine definition

Works same as well as original @apiDefine but supports embedded @apiUse.

@apiErrorPrefix

Format:

@apiErrorPrefix prefix

Prefixes all following @apiErrors with prefix.

Can be combined with @apiUse to reuse lists of apiError between different doc blocks.

Example:

/**
 * @apiDefine sharedParams
 * @apiError a
 * @apiError b
 * @apiError c
 */

/**
 * @api {post} test1
 * @apiDescription Parameters are prefixed by "body" - body.a, body.b, body.c
 * @apiErrorPrefix body.
 * @apiUse sharedParams
 */

/**
 * @api {post} test2
 * @apiDescription Parameters are prefixed by "payload" - payload.a, payload.b, payload.c
 * @apiErrorPrefix payload.
 * @apiUse sharedParams
 */

Another subsequent declaration adds a prefix to the previous one. ".." returns to the previous prefix, empty value resets the prefix.

Example:

/**
 * @api {post} test
 * @apiErrorPrefix body.
 * @apiError {String} a As "body.a"
 * @apiErrorPrefix b.
 * @apiError {String} c As "body.b.c"
 * @apiErrorPrefix ..
 * @apiError {String} d As "body.d"
 * @apiErrorPrefix
 * @apiError {String} e As "e"
 */

@apiErrorValue

Format:

@apiErrorValue [{type}] value [description]

Describes custom error value.

@apiHeaderValue

Format:

@apiHeaderValue [{type}] value [description]

Describes custom header value.

@apiFamily

Format:

@apiFamily uniqueIdentifier

Defines unique identifier of the doc block within its chapter, group and subgroup.

It can be used to distinguish between several doc blocks with the same descriptors to show them separately or combine the different doc blocks under versioning.

Example:

/**
 * @api {post} /test
 * @apiVersion v1
 * @apiFamily a
 */

/**
 * @api {post} /test
 * @apiVersion v1
 * @apiFamily b
 */

The second one does not override the first and is shown separately.

Example:

/**
 * @api {post} /v1/test
 * @apiVersion v1
 * @apiFamily a
 */

/**
 * @api {post} /v2/test
 * @apiVersion v2
 * @apiFamily a
 */

The second one is combined with the first and is shown under version.

@apiNote

Format:

@apiNote title

Adds note section that describes some additional information.

Can be used with @apiDescription.

@apiParamPrefix

Format:

@apiParamPrefix prefix

Prefixes all following @apiParams with prefix.

Can be combined with @apiUse to reuse lists of apiParam between different doc blocks.

Example:

/**
 * @apiDefine sharedParams
 * @apiParam a
 * @apiParam b
 * @apiParam c
 */

/**
 * @api {post} test1
 * @apiDescription Parameters are prefixed by "body" - body.a, body.b, body.c
 * @apiParamPrefix body.
 * @apiUse sharedParams
 */

/**
 * @api {post} test2
 * @apiDescription Parameters are prefixed by "payload" - payload.a, payload.b, payload.c
 * @apiParamPrefix payload.
 * @apiUse sharedParams
 */

Another subsequent declaration adds a prefix to the previous one. ".." returns to the previous prefix, empty value resets the prefix.

Example:

/**
 * @api {post} test
 * @apiParamPrefix body.
 * @apiParam {String} a As "body.a"
 * @apiParamPrefix b.
 * @apiParam {String} c As "body.b.c"
 * @apiParamPrefix ..
 * @apiParam {String} d As "body.d"
 * @apiParamPrefix
 * @apiParam {String} e As "e"
 */

@apiParamValue

Format:

@apiParamValue [{type}] value [description]

Describes custom parameter value.

@apiSchema

Format:

@apiSchema [(group)] {jsonschema=pathToFile[#internal.path]} @apiParam

@apiSchema [(group)] {swagger=pathToFile#internal.path.to.api} operationNickname

@apiSchema [(group)] {swagger=pathToFile#internal.path.to.model} @apiParam

Uses external schema to fill doc block.

"jsonschema" also allows to use $ref definitions within schema. "swagger" generates doc block by api operation or @apiParam list by model.

@apiSampleRequestOption

Format:

@apiSampleRequestOption key [val=true]

Defines