Skip to content

Latest commit

 

History

History
676 lines (526 loc) · 33.6 KB

README.md

File metadata and controls

676 lines (526 loc) · 33.6 KB

OpenAPI Command Line Tool

CI License npm version npm downloads npm type definitions Buy me a coffee

openapicmd - The CLI for all things OpenAPI and Swagger

Install

npm install -g openapicmd
openapi help

Features

  • Read and convert local and remote JSON/YAML OpenAPI definition files
  • Generate TypeScript types from OpenAPI definitions
  • Use as a CLI client to easily call API endpoints
  • Run Local Mock APIs
  • Automate API tests and validate specs
  • Run Swagger UI or ReDoc locally
  • Bundle static Swagger UI or ReDoc sites
  • Run Swagger Editor locally
  • Convert Swagger to OpenAPI

Commands

openapi auth [DEFINITION]

Authenticate with apis (writes to .openapiconfig)

USAGE
  $ openapi auth [DEFINITION] [-h] [-V] [-D] [-B] [-R <value>] [-H <value>] [-S <value>] [-I <value>] [-E
    <value>] [-C <value>] [-s <value>] [-k <value>] [-t <value>] [-u <value>] [-P <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -P, --password=<value>                                        set basic auth password
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -h, --help                                                    Show CLI help.
  -k, --apikey=<value>                                          set api key
  -s, --security=<value>...                                     use security scheme
  -t, --token=<value>                                           set bearer token
  -u, --username=<value>                                        set basic auth username

DESCRIPTION
  Authenticate with apis (writes to .openapiconfig)

EXAMPLES
  $ openapi auth

  $ openapi auth --token eyJh...

  $ openapi auth --security ApiKeyAuth --apikey secret123

  $ openapi auth --security BasicAuth --username admin --password password

See code: src/commands/auth.ts

openapi call [DEFINITION]

Call API endpoints

USAGE
  $ openapi call [DEFINITION] [-h] [-D] [-B] [-R <value>] [-H <value>] [-V] [-S <value>] [-I <value>] [-E
    <value>] [-C <value>] [--interactive] [-o <value>] [-p <value>] [-d <value>] [-i] [-v] [-s <value>] [-k <value>] [-t
    <value>] [-u <value>] [-P <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -P, --password=<value>                                        set basic auth password
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -d, --data=<value>                                            request body
  -h, --help                                                    Show CLI help.
  -i, --include                                                 include status code and response headers the output
  -k, --apikey=<value>                                          set api key
  -o, --operation=operationId                                   operationId
  -p, --param=key=value...                                      parameter
  -s, --security=<value>...                                     use security scheme
  -t, --token=<value>                                           set bearer token
  -u, --username=<value>                                        set basic auth username
  -v, --verbose                                                 verbose mode
  --[no-]interactive                                            [default: true] enable CLI interactive mode

DESCRIPTION
  Call API endpoints

EXAMPLES
  $ openapi call -o getPets

  $ openapi call -o getPet -p id=1

  $ openapi call -o createPet -d '{ "name": "Garfield" }'

See code: src/commands/call.ts

openapi help [COMMANDS]

Display help for openapi.

USAGE
  $ openapi help [COMMANDS] [-n]

ARGUMENTS
  COMMANDS  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for openapi.

See code: @oclif/plugin-help

openapi info [DEFINITION]

Display API information

USAGE
  $ openapi info [DEFINITION] [-h] [-D] [-B] [-R <value>] [-H <value>] [-V] [-S <value>] [-I <value>] [-E
    <value>] [-C <value>] [--security] [--operations] [--schemas]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -h, --help                                                    Show CLI help.
  --operations                                                  list operations in document
  --schemas                                                     list schemas in document
  --security                                                    list security schemes in document

DESCRIPTION
  Display API information

EXAMPLES
  $ openapi info https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

  $ openapi info ./openapi.yml

See code: src/commands/info.ts

openapi init

Initialise a definition file from scratch

USAGE
  $ openapi init [-h] [-T <value>] [-d <value>] [-v <value>] [--terms <value>] [--license mit|apache2] [-S
    <value>] [-I <value>] [-f json|yaml|yml | --json | --yaml]

FLAGS
  -I, --inject={"info":{"version":"1.0.0"}}...  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -S, --server=http://localhost:9000...         override servers definition
  -T, --title=<value>                           [default: My API] The title for the API
  -d, --description=<value>                     Description for the API
  -f, --format=<option>                         [default: yaml] output format
                                                <options: json|yaml|yml>
  -h, --help                                    Show CLI help.
  -v, --version=<value>                         [default: 0.0.1] Version of the API
  --json                                        format as json (short for -f json)
  --license=<option>                            The license for the API
                                                <options: mit|apache2>
  --terms=<value>                               A URL to the Terms of Service for the API.
  --yaml                                        format as yaml (short for -f yaml)

DESCRIPTION
  Initialise a definition file from scratch

EXAMPLES
  $ openapi init --title 'My API' > openapi.yml

See code: src/commands/init.ts

openapi load DEFINITION

Set the default definition file for a workspace (writes to .openapiconfig)

USAGE
  $ openapi load DEFINITION [-h] [-V] [-S <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -S, --server=http://localhost:9000...  override servers definition
  -V, --validate                         validate against openapi schema
  -h, --help                             Show CLI help.

DESCRIPTION
  Set the default definition file for a workspace (writes to .openapiconfig)

EXAMPLES
  $ openapi load ./openapi.yml

  $ openapi load https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

See code: src/commands/load.ts

openapi mock [DEFINITION]

Start a local mock API server

USAGE
  $ openapi mock [DEFINITION] [-h] [-p <value>] [--logger] [-S <value>] [-I <value>] [-C <value>] [-E
    <value>] [-H <value>] [-R <value>] [-U <value>] [--validate]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -U, --swagger-ui=docs                                         Swagger UI endpoint
  -h, --help                                                    Show CLI help.
  -p, --port=9000                                               [default: 9000] port
  --[no-]logger                                                 [default: true] log requests
  --[no-]validate                                               [default: true] validate requests according to schema

DESCRIPTION
  Start a local mock API server

EXAMPLES
  $ openapi mock ./openapi.yml

  $ openapi mock https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

See code: src/commands/mock.ts

openapi read [DEFINITION]

Read and manipulate definition files

USAGE
  $ openapi read [DEFINITION] [-h] [-D] [-B] [-R <value>] [-H <value>] [-V] [-S <value>] [-I <value>] [-E
    <value>] [-C <value>] [-f json|yaml|yml | --json | --yaml]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -f, --format=<option>                                         [default: yaml] output format
                                                                <options: json|yaml|yml>
  -h, --help                                                    Show CLI help.
  --json                                                        format as json (short for -f json)
  --yaml                                                        format as yaml (short for -f yaml)

DESCRIPTION
  Read and manipulate definition files

EXAMPLES
  $ openapi read https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

  $ openapi read ./openapi.yml -f json > openapi.json

See code: src/commands/read.ts

openapi redoc [DEFINITION]

Start or bundle a ReDoc instance

USAGE
  $ openapi redoc [DEFINITION] [-h] [-p <value>] [--logger] [-S <value>] [-I <value>] [-E <value>] [-C
    <value>] [-H <value>] [-R <value>] [-B <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle=outDir                                           bundle a static site to directory
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -h, --help                                                    Show CLI help.
  -p, --port=9000                                               [default: 9000] port
  --[no-]logger                                                 [default: true] log requests

DESCRIPTION
  Start or bundle a ReDoc instance

EXAMPLES
  $ openapi redoc

  $ openapi redoc ./openapi.yml

  $ openapi redoc ./openapi.yml --bundle outDir

See code: src/commands/redoc.ts

openapi swagger-editor [DEFINITION]

Start a Swagger Editor instance

USAGE
  $ openapi swagger-editor [DEFINITION] [-h] [-p <value>] [--logger] [-H <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -H, --header=<value>...  add request headers when calling remote urls
  -h, --help               Show CLI help.
  -p, --port=9000          [default: 9000] port
  --[no-]logger            [default: true] log requests

DESCRIPTION
  Start a Swagger Editor instance

EXAMPLES
  $ openapi swagger-editor

  $ openapi swagger-editor ./openapi.yml

See code: src/commands/swagger-editor.ts

openapi swagger-ui [DEFINITION]

Start or bundle a Swagger UI instance

USAGE
  $ openapi swagger-ui [DEFINITION] [-h] [-p <value>] [--logger] [-S <value>] [-I <value>] [-C <value>] [-E
    <value>] [--expand full|list|none] [--operationids] [--filter] [--deeplinks] [--withcredentials] [--requestduration]
    [-H <value>] [-R <value>] [--proxy | -B <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle=outDir                                           bundle a static site to directory
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -h, --help                                                    Show CLI help.
  -p, --port=9000                                               [default: 9000] port
  --[no-]deeplinks                                              [default: true] allow deep linking
  --expand=<option>                                             [default: list] default expansion setting for the
                                                                operations and tags
                                                                <options: full|list|none>
  --[no-]filter                                                 [default: true] enable filtering by tag
  --[no-]logger                                                 [default: true] log requests
  --[no-]operationids                                           [default: true] display operationIds
  --proxy                                                       set up a proxy for the api to avoid CORS issues
  --[no-]requestduration                                        [default: true] display request durations in "try it
                                                                now"
  --[no-]withcredentials                                        [default: true] send cookies in "try it now"

DESCRIPTION
  Start or bundle a Swagger UI instance

EXAMPLES
  $ openapi swagger-ui

  $ openapi swagger-ui ./openapi.yml

  $ openapi swagger-ui ./openapi.yml --bundle outDir

See code: src/commands/swagger-ui.ts

openapi swagger2openapi [DEFINITION]

Convert Swagger 2.0 definitions to OpenAPI 3.0.x

USAGE
  $ openapi swagger2openapi [DEFINITION] [-h] [-D] [-B] [-R <value>] [-H <value>] [-V] [-S <value>] [-I <value>] [-E
    <value>] [-C <value>] [-f json|yaml|yml | --json | --yaml]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -f, --format=<option>                                         [default: yaml] output format
                                                                <options: json|yaml|yml>
  -h, --help                                                    Show CLI help.
  --json                                                        format as json (short for -f json)
  --yaml                                                        format as yaml (short for -f yaml)

DESCRIPTION
  Convert Swagger 2.0 definitions to OpenAPI 3.0.x

EXAMPLES
  $ openapi swagger2openapi --yaml ./swagger.json > openapi.yml

See code: src/commands/swagger2openapi.ts

openapi test

Run automated tests against APIs

USAGE
  $ openapi test [-h] [-D] [-B] [-R <value>] [-H <value>] [-V] [-S <value>] [-I <value>] [-E <value>] [-C
    <value>] [--interactive] [-o <value>] [-v] [-s <value>] [-k <value>] [-t <value>] [-u <value>] [-P <value>]

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -P, --password=<value>                                        set basic auth password
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -h, --help                                                    Show CLI help.
  -k, --apikey=<value>                                          set api key
  -o, --operation=operationId...                                filter by operationId
  -s, --security=<value>...                                     use security scheme
  -t, --token=<value>                                           set bearer token
  -u, --username=<value>                                        set basic auth username
  -v, --verbose                                                 verbose mode
  --[no-]interactive                                            [default: true] enable CLI interactive mode

DESCRIPTION
  Run automated tests against APIs

EXAMPLES
  $ openapi test

  $ openapi test -o getPets

See code: src/commands/test/index.ts

openapi test add [DEFINITION]

Add automated tests for API operations

USAGE
  $ openapi test add [DEFINITION] [-h] [-D] [-B] [-R <value>] [-H <value>] [-V] [-S <value>] [-I <value>] [-E
    <value>] [-C <value>] [--auto] [-o <value>] [-n <value>] [-c all|default|Success2XX|ValidResponseBody] [-p <value>]
    [-d <value>] [-v] [--interactive] [-s <value>] [-k <value>] [-t <value>] [-u <value>] [-P <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -P, --password=<value>                                        set basic auth password
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -c, --checks=2XXStatus...                                     checks to include in test
  -d, --data=<value>                                            request body
  -h, --help                                                    Show CLI help.
  -k, --apikey=<value>                                          set api key
  -n, --name=my test                                            test name
  -o, --operation=operationId                                   operationId
  -p, --param=key=value...                                      parameter
  -s, --security=<value>...                                     use security scheme
  -t, --token=<value>                                           set bearer token
  -u, --username=<value>                                        set basic auth username
  -v, --verbose                                                 verbose mode
  --auto                                                        auto generate tests for all operations
  --[no-]interactive                                            [default: true] enable CLI interactive mode

DESCRIPTION
  Add automated tests for API operations

EXAMPLES
  $ openapi test add

  $ openapi test add -o getPet --checks all

See code: src/commands/test/add.ts

openapi typegen [DEFINITION]

Generate types from openapi definition

USAGE
  $ openapi typegen [DEFINITION] [-h] [-D] [-B] [-R <value>] [-H <value>] [-V] [-S <value>] [-I <value>] [-E
    <value>] [-C <value>]

ARGUMENTS
  DEFINITION  input definition file

FLAGS
  -B, --bundle                                                  resolve remote $ref pointers
  -C, --strip=default|all|openapi_client_axios|openapi_backend  Strip optional metadata such as examples and
                                                                descriptions from definition
  -D, --dereference                                             resolve $ref pointers
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the
                                                                spec
  -H, --header=<value>...                                       add request headers when calling remote urls
  -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
  -U, --remove-unreferenced                                     Remove unreferenced components, you can skip individual component being removed by setting `x-openapicmd-keep` to true
  -R, --root=/                                                  override API root path
  -S, --server=http://localhost:9000...                         override servers definition
  -V, --validate                                                validate against openapi schema
  -h, --help                                                    Show CLI help.

DESCRIPTION
  Generate types from openapi definition

EXAMPLES
  $ openapi typegen ./openapi.yml > openapi.d.ts

See code: src/commands/typegen.ts

openapi unload

Unset the default definition file for a workspace (writes to .openapiconfig)

USAGE
  $ openapi unload [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Unset the default definition file for a workspace (writes to .openapiconfig)

EXAMPLES
  $ openapi unload

See code: src/commands/unload.ts

Commercial support

For assistance with using openapicmd in your company, reach out at [email protected].

Contributing

openapicmd is Free and Open Source Software. Issues and pull requests are more than welcome!