https://github.com/bcoughlan/openapi-commander
Generate a Node.js command line tool from an OpenAPI definition
https://github.com/bcoughlan/openapi-commander
cli openapi3
Last synced: 3 months ago
JSON representation
Generate a Node.js command line tool from an OpenAPI definition
- Host: GitHub
- URL: https://github.com/bcoughlan/openapi-commander
- Owner: bcoughlan
- License: mit
- Created: 2022-05-27T22:55:07.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-08-18T23:15:27.000Z (10 months ago)
- Last Synced: 2025-08-19T00:26:40.252Z (10 months ago)
- Topics: cli, openapi3
- Language: TypeScript
- Homepage:
- Size: 1.22 MB
- Stars: 27
- Watchers: 2
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI Commander
Generate a Node.js command line tool from an OpenAPI definition using the
[commander](https://www.npmjs.com/package/commander) library.
```
$ node petstore.js
Usage: petstore [options] [command]
Options:
-p, --print Print the HTTP request instead of sending it. (choices: "curl", "plain")
-s, --server Server to use
-a, --auth Authorization header to send
-h, --help display help for command
Commands:
pet Everything about your Pets
user Operations about user
help [command] display help for command
$ node petstore.js pet getPetById 1
Status: 200
{
"id": 1,
"category": {
"id": 1,
"name": "Hola"
},
}
```
It can be used as a starter for writing command line tools that talk to APIs,
or as an alternative to using curl to work with APIs.
- [Features](#features)
- [Setup](#setup)
- [Examples](#examples)
* [Commands grouped by tag](#commands-grouped-by-tag)
* [Basic GET example](#basic-get-example)
* [Global options](#global-options)
+ [Custom server](#custom-server)
+ [Set Authorization header](#set-authorization-header)
+ [Print request without sending](#print-request-without-sending)
+ [Print a curl command of the request](#print-a-curl-command-of-the-request)
* [Print example request bodies](#print-example-request-bodies)
- [Build standalone binaries](#build-standalone-binaries)
- [A very incomplete TODO list...](#a-very-incomplete-todo-list)
- [Contributing](#contributing)
# Features
- Generate clean code from your spec.
- Supports Swagger 2, OpenAPI 3.0 and 3.1.
- Show examples of request bodies, using examples from the spec or generated with [openapi-sampler](https://github.com/Redocly/openapi-sampler).
- Verbose mode to see response headers.
- Print a curl command of the request.
# Setup
1. Create an npm project with `npm init` or use an existing one. Your Node.js version must be 16+
2. Install dependencies
** Note: If your project still uses CommonJS, install `openapi-commander@3` and use `.js` for the output extension.**
```
npm install commander
npm install --save-dev openapi-commander
```
3. Generate the CLI code
```
npx openapi-commander generate
```
e.g.
```
npx openapi-commander generate https://raw.githubusercontent.com/OAI/OpenAPI-Specification/old-v3.0.4-dev/examples/v3.0/petstore.yaml petstore.mjs
```
4. Run
```
node petstore.js ...
```
# Examples
## Subcommands
The commands are grouped by their first tag in the OpenAPI spec (the same logic
that Swagger UI uses).
```
~/petstore$ node petstore.js pet
Usage: petstore pet [options] [command]
Everything about your Pets
Options:
-h, --help display help for command
Commands:
updatePet [options] Update an existing pet
addPet [options] Add a new pet to the store
findPetsByStatus [options] Finds Pets by status
findPetsByTags [options] *DEPRECATED* Finds Pets by tags
getPetById Find pet by ID
updatePetWithForm [options] Updates a pet in the store with form data
deletePet [options] Deletes a pet
uploadFile [options] uploads an image
help [command] display help for command
```
## Basic GET example
```
~/petstore$ node petstore.js pet getPetById 1
Status: 200
{
"id": 1,
"category": {
"id": 1,
"name": "Hola"
},
"name": "Perrito",
"photoUrls": [
"/tmp/inflector995596007222725944.tmp"
],
"tags": [
{
"id": 1,
"name": "Bizcocho"
}
],
"status": "available"
}
```
You can also add the `-v` flag to show response headers.
## Global options
### Custom server
```
~/petstore$ node petstore.js -s https://mypetstore.example pet getPetById 1
```
Alternatively you can override it by setting the environment variable `{COMMANDNAME}_SERVER`, e.g. `PETSTORE_SERVER`.
### Set Authorization header
```
~/petstore$ node petstore.js -a 'Bearer mytoken' getPetById 1
```
Alternatively you can override it by setting the environment variable `{COMMANDNAME}_AUTH`, e.g. `PETSTORE_AUTH`.
### Print request without sending
```
~/petstore$ node petstore.js pet -a 'Bearer mytoken' -s https://mypetstore.example getPetById 1 --print plain
GET https://mypetstore.example/pet/1
Authorization: Bearer mytoken
Accept: application/json
```
### Print a curl command of the request
```
~/petstore$ node petstore.js pet -a 'Bearer mytoken' -s https://mypetstore.example getPetById 1 --print curl
curl -X GET -H 'Authorization: Bearer mytoken' -H 'Accept: application/json' 'https://mypetstore.example/pet/1'
```
## Print example request bodies
```
~/petstore$ node petstore.js pet updatePet examples
Example for application/json:
{
"id": 10,
"name": "doggie",
"category": {
"id": 1,
"name": "Dogs"
},
"photoUrls": [
"string"
],
"tags": [
{
"id": 0,
"name": "string"
}
],
"status": "available"
}
```
# Build standalone binaries
To build multi-platform standalone binaries platform I recommend [vercel/pkg](https://github.com/vercel/pkg).
# A very incomplete TODO list...
The top priority is to beef up the test suite.
- Syntax highlighting of examples
- Implement different security/auth types.
- Auto-detect request body type from file.
- Show JSON & YAML examples with comments for field descriptions.
-> Strip comments from JSON when passing in
- Strip html/markdown from description
- More serialization options https://swagger.io/docs/specification/serialization/
- application/x-www-form-urlencoded content types.
- Server templating.
- Autocomplete.
# Contributing
This is a hobby side project so I have limited time to work on issues but I will
do my best to discuss issues, review PRs and keep the project maintained. Please
open an issue for discussion before opening any significant PRs to avoid any
disappointment about project scope.