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