apidoc-openapi

Generate OpenAPI definition file from apiDoc comments

Usage no npm install needed!

<script type="module">
  import apidocOpenapi from 'https://cdn.skypack.dev/apidoc-openapi';
</script>

README

apidoc-openapi

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

toc

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 <we@forfuture.co.ke>