apidoc-plugin-ts

A plugin for apidoc that injects params like @apiSuccess and @apiParam from TypeScript interfaces. Supports extended and nested interfaces.

Getting started

npm install --save-dev apidoc @jchoelt/apidoc-plugin-ts

yarn add -D apidoc @jchoelt/apidoc-plugin-ts

The following custom api-doc params are exposed:

• @apiParamInterface
• @apiQueryInterface
• @apiBodyInterface
• @apiSuccessInterface
• @apiSuccess[XYZ]Interface - when XYZ is the response HTTP status code (example 404), which can be in the 5xx form (xx instead of the last 2 digits).

@CUSTOM_PARAM (optional path to definitions file) {INTERFACE_NAME}

Example

Given the following interface:

// filename: ./employers.ts

export interface Employer {

  /**
   * Employer job title
   */
  jobTitle: string;

  /**
   * Employer personal details
   */
  personalDetails: {
    name: string;
    age: number;
  }

  /**
   * This field is for internal use.
   * @private
   */
  privateDetails: string;
}

and the following custom param:

@apiSuccessInterface (./employers.ts) {Person}

under the hood this would transpile to:

@apiSuccess {String} jobTitle Job title
@apiSuccess {Object} personalDetails Employer personal details
@apiSuccess {String} personalDetails.name
@apiSuccess {Number} personalDetails.age

Note if the Person interface is defined in the same file then you can drop the path:

@apiSuccessInterface {Person}

You can add @private or @ignore to the field documentation to omit it from the output.

Troubleshooting

Phantom API entries when referencing external files

When using a path to reference an interface in an external file (e.g. @apiSuccessInterface (../../types/api.ts) {MyType}), you may see phantom entries in the generated documentation with empty type, url, and name fields, and the file's absolute path as the group title.

This happens because apidoc independently scans all .ts files in its configured source directories. If the external type file falls within apidoc's scan path, apidoc will try to parse its JSDoc comments as API documentation blocks, producing these phantom entries.

To fix this, exclude the type definition files from apidoc's scan using excludeFilters in your apidoc.json:

{
  "excludeFilters": ["types/"]
}

Alternatively, move your type definition files outside of apidoc's configured source directories.