apidoc-openapi

Generate OpenAPI definition file from apiDoc comments in your source code.

toc

• installation
• usage
  • source code
  • command-line
• license

installation

$ npm install @forfuture/apidoc-openapi

usage

source code

It is important to note that this tool supports any programming language that apiDoc supports. However, we shall use JavaScript in our documentation.

The tool expects a certain style of writing your apiDoc comments. For example,

/**
 * @api {put} /users/:userId Update user
 * @apiName UpdateUser
 * @apiGroup Users
 * @apiDescription Update user's information
 *
 * @apiParam {String} userId User's unique ID
 * @apiParam {String} [firstName] User's first name
 * @apiParam {String} [lastName] User's last name
 *
 * @apiSuccess (200) {Object} data Data object
 * @apiSuccess (200) {Boolean} data.ok Set to `true` always
 */

1. We have (visually) grouped our comments into 3 groups:
   • informational group: identifies and describes the API endpoint.
   • parameters group: lists the API parameters e.g query parameters.
   • responses group: list the expected responses from the endpoint.
2. In the informational group, ensure you provide:
   • name (@apiName)
   • group (@apiGroup)
   • description (@apiDescription)
3. You MUST provide at least 1 success reponse (@apiSuccess) in the responses group.
4. In the responses group, ensure you provide:
   • HTTP status code e.g. (200)

command-line

You operate the tool from your command-line. For example (in BASH),

$ apidoc-openapi --help

  Usage: apidoc-openapi [options]

  Options:

    -V, --version         output the version number
    -p, --project <path>  path to apidoc config file
    -s, --src <path>      path to source files
    -o, --out <path>      path to output file
    -v, --verbose         be verbose
    -h, --help            output usage information

To generate an OpenAPI definition file:

$ apidoc-openapi --project ./apidoc.json --src src/ --out ./openapi.json

license

The MIT License (MIT)

Copyright (c) 2018 Forfuture LLC <[email protected]>