Nice Philanthropist Metalhead

    @commercetools-docs/gatsby-transformer-raml

    12.0.1 • Public • Published

    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'],
            movePropertiesToTop: ['id'],
            movePropertiesToBottom: ['custom'],
          },
        },
      ],
    };

    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.
    • movePropertiesToTop: This is the list of API type properties that must be sorted to the top.
    • movePropertiesToBottom: This is the list of API type properties 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'],
            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
        }
      }
    }

    Install

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

    DownloadsWeekly Downloads

    684

    Version

    12.0.1

    License

    MIT

    Unpacked Size

    43.7 kB

    Total Files

    37

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar