@commerce-apps/raml-toolkit NPM

Raml Toolkit

A collection of RAML and OAS tools for commerce cloud and beyond

Note: Running some OAS commands requires that oasdiff is installed. Install oasdiff according to https://github.com/oasdiff/oasdiff#installation

Installation
Usage
SDK Ready for Mercury
Contributing
Known issues and limitations
Development Resources

Installation

npm install -g @commerce-apps/raml-toolkit

Usage

Npm installs the binaries as both raml-toolkit and ramlint and they can be used interchangeably. You can always run with --help to get available options, currently the options are as follows.

Commands

Note: Some commands require environment variables to be set. This can be done using a .env file in your working directory (the directory from which you run raml-toolkit).

`raml-toolkit generate`

A wrapper command for openapi-generator-cli generate

USAGE
  $ raml-toolkit generate -i OAS_spec_file -o output_dir -t templates_dir

OPTIONS
  -i, --inputSpec=OAS_spec_file                   Format of the output. Defaults to JSON if --out-file is specified,
                                                  otherwise text.

  -o, --outputDir=output_dir                      The directory to place the generated API

  -t, --templateDir=template_dir                  The directory with the mustache templates for generating the API

  -c, --configFile=config_file                    A yaml file containing configurations for openapi-generator-cli. A default configuration will be used if this is not provided.

  -g, --generator                                 The generator. Defaults to `typescript-fetch`

  --skipValidateSpec                               Generate API without validating the spec. Defaults to false.

`raml-toolkit diff BASE NEW -s oas`

Note: This command requires that oasdiff is installed. Install oasdiff according to https://github.com/oasdiff/oasdiff#installation

USAGE
  $ raml-toolkit diff BASE NEW -s oas

ARGUMENTS
  BASE  The base API spec file or directory
  NEW   The new API spec file or directory

OPTIONS
  -f, --format=(json|console)                     Format of the output. Defaults to JSON if --out-file is specified,
                                                  otherwise text.

  -o, --out-file=out-file                         File to store the computed difference

  --dir                                           Find the differences for files in two directory trees

  -s, --spec                                      Toggles OAS mode. Set this to `oas`. Otherwise, the command will run the RAML version

Commands for RAML

raml-toolkit diff BASE NEW
raml-toolkit download
raml-toolkit lint [FILENAME]

`raml-toolkit diff BASE NEW`

Compute the difference between two API specifications

USAGE
  $ raml-toolkit diff BASE NEW

ARGUMENTS
  BASE  The base API spec file (ruleset / diff-only mode) or directory
  NEW   The new API spec file (ruleset / diff-only mode) or directory

OPTIONS
  -f, --format=(json|console)                     Format of the output. Defaults to JSON if --out-file is specified,
                                                  otherwise text.

  -o, --out-file=out-file                         File to store the computed difference

  -r, --ruleset=ruleset                           [default:@commerce-apps/raml-toolkit/resources/diff/rules/defaultRules
                                                  ] Path to ruleset to apply to diff

  --diff-only                                     Only show differences without evaluating a ruleset

  --dir                                           Find the differences for files in two directory trees and applies
                                                  default ruleset

  --log-level=trace|debug|info|warn|error|silent  [default: info] Set the level of detail in the output

DESCRIPTION
  This command has three modes: ruleset, diff-only, and directory.
  - Ruleset mode (default) compares two files and applies a ruleset to determine if any changes are breaking.
  - Diff-only mode compares two files to determine if there are any differences, without applying a ruleset.
  - Directory mode finds all exchange.json files in two directories recursively and compares all the spec files 
  described in them. Applies the default ruleset.

  In ruleset and diff-only mode, the arguments must be API specification (RAML) files.
  In directory mode, the arguments must be directories that contain exchange.json files.

  Exit statuses:
     0 - No breaking changes (ruleset mode) or no differences (diff-only / directory)
     1 - Breaking changes (ruleset mode) or differences found (diff only / directory)
     2 - Evaluation could not be completed

`raml-toolkit download`

Download API specification files from Anypoint Exchange

USAGE
  $ raml-toolkit download

OPTIONS
  -d, --dest=dest                                  [default: apis] Directory to download APIs into

  -s, --search=search                              Search query to filter results from Anypoint Exchange

  --log-level=trace|debug|info|warn|error|silent   [default: info] Set the level of detail in the output

`raml-toolkit lint [FILENAME]`

A linting tool for raml for Commerce Cloud and beyond

USAGE
  $ raml-toolkit lint [FILENAME]

ARGUMENTS
  FILENAME  One or more RAML files to lint

OPTIONS
  -p, --profile=(mercury|slas)                    (required) Profile to apply
  -w, --warnings                                  Show all the warnings
  --log-level=trace|debug|info|warn|error|silent  [default: info] Set the level of detail in the output

Additional Information

For additional information on the diff command, see these resources:

Jenkins

In your Jenkinsfile, init npm and then it's a simple one line command

  stage('Init') {
      // Needed only for SFCI instances to add npm to the instance
      npmInit()
  }

  stage('Whatever') {
      sh "npx raml-toolkit lint --profile mercury file1.raml file2.raml etc.raml"
  }

NOTE: Violations will return a non-zero exit code and fail the build, which warnings will still return a 0 exit code so the build will not fail with warnings

From your local machine

To check your RAML currently the CLI just takes a list of files

$ ramlint lint --profile mercury file.raml
# or
$ ramlint lint --profile mercury file1.raml file2.raml etc.raml

The response will look something like

Model: file://data-products-api-v1.raml
Profile: mercury
Conforms? false
Number of results: 2

Level: Violation

- Source: http://a.ml/vocabularies/data#require-api-description
  Message: The API Description must be set
  Level: Violation
  Target: file://data-products-api-v1.raml#/web-api
  Property: http://schema.org/description
  Position: Some(LexicalInformation([(2,0)-(1885,0)]))
  Location: file://data-products-api-v1.raml

- Source: http://a.ml/vocabularies/data#version-format
  Message: The version must be formatted as v[Major], for example v2
  Level: Violation
  Target: file://data-products-api-v1.raml#/web-api
  Property: http://schema.org/version
  Position: Some(LexicalInformation([(3,9)-(3,11)]))
  Location: file://data-products-api-v1.raml

 ›   Error: ./data-products-api-v1.raml is invalid

Let us look more closely at each of these errors.

The first error is saying that the API description is not set, but we need to have it set according to our standards. There is a "Position:" field in the response, but it is saying 2-1885. This happens to be the entire RAML document. Ranges like this will be common for "Missing" components since the parser doesn't know where you want to put it, but knows you need to put it somewhere.

The second error, however, is because it exists, but doesn't match our standard. There you can see that the position leads you to the exact line number and column of the non-conforming component.

When there are no more violations, the output will say it conforms, but also provide you with some warnings you might want to fix as well.

Exchange Connector

This package also contains the code formerly published under @commerce-apps/exchange-connector. There are no breaking changes between the last version of @commerce-apps/exchange-connector and v0.3.0 of this package. For changes since then, see the changelog.

SDK Ready for Mercury

The default profile validates the following rules from the Mercury API Definition of Done

title MUST be set and not be empty
protocols MUST be HTTPS
version MUST be set and follow the pattern /v0-9+/
API must have a mediaType default of application/json
description MUST be set and not be empty
description MUST not include the word TODO
All resource paths MUST be lowercase (except template parameters)
Resource paths MUST not start with symbols
All template/URI params MUST be lowerCamelCase
Methods MUST have a displayName set
Method displayName MUST be in camelCase
Methods MUST have a description field set
Method description MUST NOT contain the word TODO
queryParameters MUST be camelCase
Response codes MUST have a description
Response codes description MUST NOT contain the word TODO
There must be exactly one baseUri
baseUri must match the pattern - https://{shortCode}.api.commercecloud.salesforce.com/<api-family>/<api-name>/{version}
displayName must be unique across an API