README

api-spec-helper

api-spec-helper is a CLI tool meant to help you generate API documentation based on the OAS3.
It generates simple stubs for user-specified paths, allowing you to add methods and responses to your requests automatically. You will still need to customize requestBody properties, request parameters and response schemas. You will also need to fix the indentation in some parts, unfortunately. It is currently in the early stages of development, and only supports JSON formatting.

Installation

Install globally on your computer:

  npm install -g api-spec-helper

Usage

Run api-spec-helper --help to get a list of commands and arguments.

api-spec-helper command references:
  -h      --help                        Display this help message.
  
  -a      --add-path                    Adds routes to specific paths. Expects arguments:
  -p        --paths=users,estates         Specify which paths will be documented.
  -t        --tag='Admin Panel'           Specify a single tag to the generated paths.
  -m        --methods=GET,PUT,DELETE      Specify which methods will be generated. Defaults to all 4.
  -r        --responses=200,203           Specify HTTP status codes for responses. Defaults to 200, 204, 401 & 404.
  
  -g       --generate-stub               Generate barebones OAS3 file. Accepts the following arguments:
  -t         --tag='Admin,Customer'      Specify your project's tags, which will be referenced in your paths. Comma-separated.
  -n         --name='Application'        Specify your application's title.

Examples

generate-stub

  api-spec-helper -g -t 'Admin Panel'

will be equivalent to

  api-spec-helper --generate-stub --tag 'Admin Panel'

and will generate the following json in stdout:

{
    "openapi": "3.0.0",
    "info": {
      "version": "0.1.0",
      "title": "Application Title",
      "description": "Application Description"
    },
    "servers": [
      {
        "url": "http://localhost",
        "description": "Your local application server"
      }
    ],
    "tags": [
       {"name": "Admin Panel", "description": "Tag description"}
    ],
    "paths": {

add-path

  api-spec-helper -a -p users,estates -t 'Admin Panel' -m GET,POST -r 200

will be equivalent to

  api-spec-helper --add-path --paths=users,estates --tag='Admin Panel' --methods=GET,POST --responses=200

and will generate the following json in stdout:

"/users": {
 "get": {
      "tags": ["Admin Panel"],
      "summary": "",
      "responses": {
        "200": {"description": "OK"}
      }
    },
  "post": {
      "tags": ["Admin Panel"],
      "summary": "",
      "requestBody": {
        "description": "",
        "content": {

        }
      },
      "responses": {
        "200": {"description": "OK"}
      }
    }
},
"/estates": {
 "get": {
      "tags": ["Admin Panel"],
      "summary": "",
      "responses": {
        "200": {"description": "OK"}
      }
    },
  "post": {
      "tags": ["Admin Panel"],
      "summary": "",
      "requestBody": {
        "description": "",
        "content": {

        }
      },
      "responses": {
        "200": {"description": "OK"}
      }
    }
},

You can choose to send your output for a specific text file or simply copy-paste the stubs on your swagger.json file. Then, adapt and add content as necessary.

Contributing

Please visit the Contributing Guide.

License

MIT

Usage no npm install needed!