Community Plugin
View plugin on GitHub
See starters using this

Gatsby Theme Add-On for API docs

This theme provides components in MDX to render API info from RAML spec files.

It is a feature add-on to @commercetools-docs/gatsby-theme-docs and is not usable standalone.

Installation

npx install-peerdeps --dev @commercetools-docs/gatsby-theme-api-docs

Usage

In your gatsby-config.js:

const {
  configureThemeWithAddOns,
} = require('@commercetools-docs/gatsby-theme-docs/configure-theme');

module.exports = {
  // ... other site config
  plugins: [
    ...configureThemeWithAddOns({
      // ... other theme config
      addOns: [
        {
          resolve: '@commercetools-docs/gatsby-theme-api-docs',
          options: {
            transformerRaml: {
              includeApis: ['example'],
              movePropertiesToTop: ['id'],
              movePropertiesToBottom: ['custom'],
            },
          },
        },
      ],
    }),
  ],
};

Plugin Options

Generating the required canonical RAML form

Use the @commercetools-docs/rmf-codegen RAML_DOC target output to generate RAML API specifications in the canonical file layout required by this plugin. It does an (any valid) RAML to (canonical flattened) RAML conversion allowing the gatsbyJS plugin to handle the RAML literally without parsing or resolving.

Example call:

npx rmf-codegen generate ./websites/api-docs-smoke-test/source-raml/test/api.raml --output-folder ./websites/api-docs-smoke-test/src/api-specs/test --target RAML_DOC

In gatsby develop mode, add the --watch option to the rmf-codegen command to continuously regenerate the canonical output while editing the original RAML.

Path Convention ./src/api-specs/

RAML spec files have to be added in the ./src/api-specs/ folder of the website. This directory is required and is automatically generated when the plugin runs.

The file location determines the apiKey through which it can be addressed:

  • src/api-specs/foo.raml -> apiKey foo
  • src/api-specs/bar/api.raml -> apiKey bar
  • src/api-specs/baz/baz.raml -> apiKey baz

Overriding the location of certain API types

If you want to override the location to link to for certain API data types, create a file called type-locations.yaml under the src/data folder of the website. This can be useful to choose manual markdown based documentation for certain types or to link ot shared types used on other websites like public standards. Use the following format to override the type locations:

- api: import
  locations:
    - type: AssetDimensions
      href: /product-variant#assetdimensions
    - type: DiscountedPrice
      href: /../other-microsite/order#discountedprice
- api: history
  locations:
    - type: LocalizedLabel
      href: https://example.com/some/other/location/on/the/web
  • api -> Name of the api where the types are located.
  • locations -> List of type locations you want to override.
  • type -> Name of the type to override.
  • href -> Your custom link.

Using UI components in MDX

The package exposes the following components in the MDX context:

  • <ApiType>: Renders an API type.
{
  /*
  apiKey - name of the specs directory
  type - name of the api type
  hideInheritedProperties - optional prop that hides properties inherited from parent type except discriminator
*/
}
<ApiType apiKey="test" type="ExamplesTestType" hideInheritedProperties />;
  • <ApiEndpoint>: Renders an API endpoint.
{
  /*
  apiKey - name of the specs directory
  resource - path of the endpoint
  method - endpoint method e.g. get, post, delete.
  title - optional title to render
*/
}
<ApiEndpoint
  apiKey="test"
  resource="/{projectKey}/resource/artificially-complex/path/uri-parameter-one={uriParameterOne}/{uriParameterTwo}"
  method="POST"
  title="<optional>"
/>;
  • <ApiEndpointsForResource>: Renders all endpoints of an API resource.
{
  /*
  apiKey - name of the specs directory
  resource - path of the resource
*/
}
<ApiEndpointsForResource apiKey="test" resource="/{projectKey}/resource" />;