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

Soft links are autogenerated for types and endpoints that are used on MDX pages. They are generated using our custom URN, for types the custom URN is ctp:<api-key>:type:<type-name>, and for endpoints the custom URN is ctp:<api-key>:endpoint:<endpoint>:<method>.

Soft links can be taken advantage of in a couple of ways:

  1. If the type of a field is used on an MDX page, the type would be automatically rendered as a link, instead of a text, to where the type is rendered/defined on the MDX page.
  2. Our custom URN can be used in markdown links of description fields of types and resources. For example, to use an autogenerated soft link for a type, the markdown link would be written as [Text](ctp:<api-key>:type:<type-name>).

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

Because the API documentation components load the complete API specification data, they are not automatically injected into the MDX provider but have to be imported explicitly.

By convention it’s recommended that websites define a /shortcodes.js module that can then be addressed in the MDX pages:

export {
  ApiType,
  ApiEndpoint,
  ApiEndpointsForResource,
} from '@commercetools-docs/gatsby-theme-api-docs';

The package exposes the following components:

  • <ApiType>: Renders an API type.
import { ApiType } from '/shortcodes';
{
  /*
  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.
import { ApiEndpoint } from '/shortcodes';
{
  /*
  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.
import { ApiEndpointsForResource } from '/shortcodes';
{
  /*
  apiKey - name of the specs directory
  resource - path of the resource
*/
}
<ApiEndpointsForResource apiKey="test" resource="/{projectKey}/resource" />;

Resource Query Paramesters of Array Type

All query parameters of array type are not rendered as arrays. Only the type (for example String) of the array items is rendered along with additional text in the description that reads The parameter can be passed multiple times..