@forfuture/apidoc-openapi
Generate OpenAPI definition file from apiDoc comments
Last updated 2 years ago by gochomugo .
MIT · Original npm · Tarball · package.json
$ cnpm install @forfuture/apidoc-openapi 
SYNC missed versions from official npm registry.

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>

Current Tags

  • 0.0.1                                ...           latest (2 years ago)

2 Versions

  • 0.0.1                                ...           2 years ago
  • 0.0.0                                ...           2 years ago
Downloads
Today 0
This Week 2
This Month 2
Last Day 1
Last Week 0
Last Month 4
Dependencies (3)
Dev Dependencies (0)
None
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |