Community Plugin
View plugin on GitHub
See starters using this

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 the original RAML using RMF-codegen to have a strict canonical form.

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: {
        includeApis: ['example'],
        moveTypePropertiesToTop: ['id'],
        moveTypePropertiesToBottom: ['custom'],
        moveEndpointQueryParametersToTop: ['where'],
        moveEndpointQueryParametersToBottom: ['/^var[.][a-zA-Z0-9]+$/'],
      },
    },
  ],
};

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.

Available Plugin Options

  • includeApis: This is a list of the names each API specifications directory located in ./src/api-specs. Only APIs listed here will be available on the website.
  • moveTypePropertiesToTop: This is the list of API type properties that must be sorted to the top.
  • moveTypePropertiesToBottom: This is the list of API type properties that must be sorted to the bottom.
  • moveEndpointQueryParametersToTop: This is the list of endpoint query parameters that must be sorted to the top.
  • moveEndpointQueryParametersToBottom: This is the list of endpoint query parameters that must be sorted 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'],
        moveTypePropertiesToTop: ['id', 'name', 'surname'],
        moveTypePropertiesToBottom: ['last-property'],
        moveEndpointQueryParametersToTop: ['where', 'sort', 'limit'],
        moveEndpointQueryParametersToBottom: [
          'expand',
          '/^var[.][a-zA-Z0-9]+$/',
        ],
      },
    },
  ],
};

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
    }
  }
}