Skip to content
Docs
CLI

Command Line Interface (CLI)

In order to run the command line interface tool, you can install it with npm:

npm install -g @oas-tools/cli

Then you can run any commands through oas-tools <command>. Besides, it is also possible to run OAS Tools CLI command with npx:

npx @oas-tools/cli <command>

The following sections describe the different commands available through the CLI tool, you can always check them out by running oas-tools --help.

Init

The init command is used for initializing a resource. The available resources to initialize are described in the following sections, you can configure each of them after running:

oas-tools init

An interactive menu will prompt, where you can choose a resource to initialize and configure it easily by answering some questions. However, the interactive prompt is not compatible with every terminal, taht's why it is possible to run each command the traditional way, as the following sections describe.

Server

A REST service can be initialized through the command line tool by running the following command:

oas-tools init server <OpenAPI v3 file in YAML or JSON> [options]

The possible options are listed in the table below:

OptionDefaultDescription
-n, --path-name <dirpath>generated-serverPath for the generated directory
-p, --port <port>8080Port to which the server will be listening
-r, --recursive-Generate path-name directories recursively
-d, --dereference-Dereference the OpenAPI document
-m, --esm-Use ESM syntax instead of CommonJS
-j, --json-Generate oas-doc file as JSON instead of YAML
-c, --container-Generate required files to build Docker image
-z, --zip-Generate a zip and delete the folder
-h, --help-Display help for command

Module

A Module can be initialized through the command line tool by running the following command:

oas-tools init module <Module name> [options]

The possible options are listed in the table below:

OptionDefaultDescription
--generate-server-Generate a test server for the new module
-m, --esm-Use ESM syntax instead of CommonJS
-h --help-Display help for command

Bear in mind that using ESM syntax will set the type: module in the generated package.json. You may need to use a transpiler like Babel.js or move to Typescript in order for the new module to be usable on CommonJS servers.

Development environment

A complete development workspace can be initialized through the command line tool by running the following command:

oas-tools init dev-env [options]

The possible options are listed in the table below:

OptionDefaultDescription
-g, --git-repo <url>https://github.com/oas-tools/oas-tools.gitClone OAS Tools from a repository
-b, --git-branch <name>developBranch to clone the repo from
--clone-commons-Clone the commons library
-h --help-Display help for command

OpenAPI File

⚠

This command is not recommended to use in the traditional way when provided a file with too many resources declared. Instead switch to a terminal which have interactive support and run oas-tools init or create the OpenAPI declaration manually.

This command lets you generate a valid OpenAPI file from an entity resource:

oas-tools init file <Resource file> -n <names> -i <ids> -o <operations> [options]
OptionRequiredDefaultDescription
-n, --resource-name <name...>true-List containing each resource name
-i, --id-property <ids...>true-List containing each resource id property
-o, --operationstrue-Object containing available operations for each resource. the object format is: name=op1,op2,op3...
-v, --version <version>false3.0.3The OpenAPI version that will be used
-t, --title <title>falseAutogenerated ApiTitle for the described API
-d, --description <text>falseGenerated with OAS Tools CLIDescription for the described API
-p, --path-name <path>falseprocess.cwd()/oas-doc.[json|yaml]Path where the file will be generated
-j, --json-Generate oas-doc file as JSON instead of YAML
-h --help-Display help for command

For example, given the following resource declaration:

// resources.json
[
    {
        "userId": 1,
        "name": "User",
        "email": "user@example.com"
    },
    {
        "petId": 1,
        "petName": "Garfield",
        "type": "Cat"
    }
]

A valid OpenAPI declaration could be generated running the following command:

oas-tools init file ./resources.json -n User Pet -i userId petId -o User=GET,POST,PUT Pet=GET

The command above will generate an OpenAPI declaration in which the resource User has three operations: GET, POST and PUT, whereas the resource PET has only a GET operation.

Validate

The validate command is a simple instruction that takes no options. Its only purpose is to validate an OpenAPI document in the same way that OAS Tools core library does. It will output validation errors formatted as explained in the Validation section.

oas-tools validate <path to OpenApi file>
Handling errors
Advanced project Setup