@ama-openapi/cli
[!WARNING] Experimental: This package is available in early access, the final version will be released in v15.
A command-line interface (CLI) tool for managing OpenAPI specifications and their dependencies through manifest files.
Description
The @ama-openapi/cli package provides a CLI tool to automate the installation and management of OpenAPI specifications based on manifest files.
It's part of the AMA OpenAPI ecosystem that helps manage OpenAPI dependencies in your projects.
Installation
Global Installation
npm install @ama-openapi/cli
[!INFO] The package needs to be installed as a
dependencyto allow model sharing.
Usage
The CLI is available through the ama-openapi command and provides the following functionality:
ama-openapi <command> [options]
The following global options can be used with any command:
| Option | Type | Default | Description |
|---|---|---|---|
--log-level, -l | "silent" | "error" | "warning" | "info" | "debug" | error | Define the specific level of logs to display in the console |
--help, -h | Show help information |
Available commands
install command
This command scans for manifest files in the current working directory and installs all OpenAPI specifications specified in those files. The installation process will download and process the OpenAPI specifications according to the configuration in your manifest.
ama-openapi install [options]
Examples:
# Install dependencies from manifest files
ama-openapi install
# Install with debug output
ama-openapi install --debug
# Install silently
ama-openapi install --silent
watch command
This command starts a file watcher that monitors manifest files for changes. When a manifest file is modified, it automatically triggers the installation process, ensuring your OpenAPI specifications are always up to date during development.
ama-openapi watch [options]
Examples:
# Start watching manifest files
ama-openapi watch
# Watch with debug output
ama-openapi watch --debug
generate-schema command
Generate the JSON Schemas that can be used for configuration auto completion.
npm exec @ama-openapi/cli generate-schema -- [options]
Options
| Option | Alias | Description | Default value |
|---|---|---|---|
--output | -o | Output directory where to generate the schemas | './schemas' |
--keywords | -k | List of the keywords to include in the artifact to be considered in the schema generation | ['openapi'] |
Expose shareable models
To expose models from the OpenAPI package, the following setups are required:
- The
models/(or any shareable folder) should be listed in package.json exports field. - The
models_external/should be should be listed in package.json exposed folders. - The
models_external/folder, with its content, must be present in the installed package
To ensure the correct resolution of the dependencies with the versions required by the final specification, the presence of the models_external/ can be achieved only through a postinstall process.
// package.json file
{
"name": "@my/spec",
"scripts": {
"postinstall": "ama-openapi install"
}
}
[!NOTE] Find more information regarding the model dependency resolution on @ama-openapi/core documentation.
[!TIP] The repository generator from @ama-openapi/create configures the package to allow the models exposition by default.
Integration
This CLI tool is designed to work seamlessly with:
- @ama-openapi/core: Core dependency management functionality
- @ama-openapi/redocly-plugin - Redocly CLI integration
- @ama-openapi/create - Project scaffolding tool