Gatsby Transformer RAML

Overview

This plugin parses RAML documents as YAML documents using JS-YAML parser. The parsed RAML documents are expected to be autogenerated from rmf-codegen.

Autogenerating RAML Documents

Get a copy of the latest rmf-codegen, run a cli in the root directory, then do the following steps:

1. Create jar file

./gradlew shadow

2. Copy jar file to main

cp tools/cli-application/build/libs/rmf-gen.jar .

3. Generate flattened raml files from api.raml

time ./rmf-gen.sh generate -o <output-directory> -t ramldoc <target-document>

For more info about the rmf-codegen commands, run this:

time ./rmf-gen.sh help generate

Installation

npm install @commercetools-docs/gatsby-transformer-raml

Usage

As a prerequisite configure gatsby-source-filesystem plugin to point the directory of the auto-generated RAML specs, for example src/api-specs. The apiKey for each node on GraphQL is derived from the api.raml directory.

Example gatsby-config.js content:

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `api-specs`,
        path: `${__dirname}/src/api-specs`,
      },
    },
    {
      resolve: `@commercetools-docs/gatsby-transformer-raml`,
      options: {},
    },
  ],
};

API Specs Directory Structure

One of the benefits of the gatsby-transformer-raml tool is that it supports multiple api specs parsing. For this to work properly, we recommend setting up the specs root directory such that all the specs directory are flattened. See example below:

├── src
│ ├── api-specs
│ │ ├── first-api-spec
│ │ | ├── api.raml
│ │ ├── second-api-spec
│ │ | ├── api.raml
│ │ ├── third-api-spec
│ │ | ├── api.raml
│ ├── pages
├── node_modules
├── README.md
├── package.json
└── .gitignore

The example above assumes the RAML specs are sourced from the api-specs directory.

Options

The following options are available:

• includeApis: A list of apis that should be parsed. Note that no api is parsed if nothing is included in this list.
• movePropertiesToTop: A list of API type properties required to be sorted to the top.
• movePropertiesToBottom: Sorts API type properties like movePropertiesToTop, but to the bottom.

Example gatsby-config.js content:

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `@commercetools-docs/gatsby-transformer-raml`,
      options: {
        includeApis: ['test'],
        movePropertiesToTop: ['id', 'name', 'surname'],
        movePropertiesToBottom: ['last-property'],
      },
    },
  ],
};

A typical GraphQL query

Example for reading all types:

{
  allRamlType {
    nodes {
      apiKey
      builtinType
      constant
      description
      discriminator
      discriminatorValue
      displayName
      enumDescriptions {
        name
        description
      }
      enumeration
      examples {
        name
        displayName
        description
        value
      }
      oneOf
      properties {
        beta
        builtinType
        constant
        default
        deprecated
        description
        discriminatorValue
        enumeration
        items {
          type
        }
        maxItems
        maxLength
        maximum
        minItems
        minLength
        minimum
        name
        pattern
        required
        type
        uniqueItems
      }
      refersTo
      type
    }
  }
}