servicelib-node/spec

The spec package within servicelib-node is for automatically generating an OpenAPI v3 specification in YAML from JSDoc YAML. servicelib-node/spec will combine all JSDoc YAML in valid OpenAPI format from the specificed route files into a single OpenAPI YAML file.

JSDoc blocks for each route require an @openapi annotation. In this example, $ref references test/fixtures/test-component.yaml and will be resolved to the YAML object from test-component.yaml.

/**
 * @openapi
 * /hello:
 *   get:
 *     summary: Hello World dndpoint
 *     description: Echoes back hello world
 *     tags:
 *       - Example API
 *     responses:
 *       200:
 *          description: Success
 *          content:
 *           application/json:
 *             schema:
 *               $ref: 'test/fixtures/test-component.yaml'
 *
 */
router.get('/hello', (req, res) => {});

Usage

To generate the specification, you can either use the CLI executable or explicitly call its functions.

Command Line

servicelib-spec -- <info-path> <routes-path> [spec-path]

info-path

Path to file where general service info is. Must include name, description, and version values. Typically is the relative path to package.json. However, you may provide a different .json config file to take service info values from.

routes-path

Path to directory with route files containing OpenAPI JSDoc yaml. Example: ./routes/*.js will search all Javascript files for @openapi annotations.

Optional

[spec-path] The path to write the openapi spec file to. Default value is ./static/openapi.yaml (which assumes a /static directory exists).

Function call

This package also exposes functions to call explicitly, if you prefer not to use the CLI executable. The main difference being that you can provide a JSON object that contains the required name, version, and description attributes instead of providing a path to a file.

generateScript(info-path, routes-path)

Returns the OpenAPI spec in YAML

writeFile(spec-path)

Write the generated YAML spec to a file

Example:

const { spec } = require('servicelib-node/spec);

const serviceInfo = { name: 'my-name', description: 'my-desc', version: '1.0.0' }

// generate the spec as
const openapiSpec = spec.generateScript(serviceInfo, ./path/to/routes/*.js);

// writes the spec to specific path
spec.writefile(./static/openapi.yaml);