jsdoc2spec

Generate structured API specification from your jsdoc.

See nodejs example

Install

npm install jsdoc jsdoc2spec

Usage

Generating specification

jsdoc2spec requires the json-formatted output from jsdoc as input, instructions on how to use jsdoc can be found on the project's homepage.

The jsdoc-json input can be provided in two ways:

Pipe output from jsdoc to jsdoc2spec

npx jsdoc src -r -X | jsdoc2spec

npx jsdoc src -r generates documentation from files found in ./src and its subfolders.

-X flag writes jsdoc-json to stdout, which is then piped to jsdoc2spec.

Use jsdoc2spec as template

npx jsdoc src -r -t jsdoc2spec

-tspecifies jsdoc2spec as the output template for jsdoc.

CLI

jsdoc2spec

Options:
  -c, --config       Path to config file  [string] [default: null]
  -x                 Output to stdout  [boolean] [default: false]
  -j, --jsdoc        Path to jsdoc-json file  [string]
  -o, --output.file  File to write to  [string]
  -h, --help         Show help  [boolean]
  -v, --version      Show version number  [boolean]

More options can be set through a config file.

Configuration

module.exports = {
  api: { // info about the generated API
    name: /* string */,
    description: /* string */,
    version: /* string */,
    license: /* string */,
    stability: /* 'experimental' | 'stable' | 'locked' */,
  },
  output: {
    file: 'spec.json', // file to write to
  },
  jsdoc: /* string */, // location of jsdoc-json file
  spec: {
    validate: true, // set to false to skip validation against schema
  },
  parse: {
    tags: {
      include: undefined, // an array of white listed tags, e.g. ['committer']
      exclude: undefined, // an array of black-listed tags (not used if 'include' is an array), e.g. ['owner']
    },
    rules: {
      'no-unknown-types': 1,
      'no-missing-types': 1,
      'no-multi-return': 1,
      'no-unknown-stability': 2,
      'no-duplicate-references': 1,
      'no-untreated-kinds': 1,
      'no-default-exports-wo-name': 1,
    }
  }
}

Rules

Parsing rules work a lot like eslint rules and are meant to warn/error when weirds things are found in the jsdoc comments.

More details on rules.