This package has been deprecated

Author message:

superseded by @commercetools-docs/gatsby-theme-docs

@commercetools-docs/gatsby-theme-commercetools-docs

Import API documentation site

This package contains the Gatsby documentation site for the Import API. The site is a mix of MDX (Markdown with react) and React components which auto-generate the API documentation from the RAML definition.

Installing Gatsby

The Import API uses the Gatsby static site generator. In addition to this documentation, take a look at Gatsby's docs for more information.

Install and run

To run Gatsby, you need:

• node.js
• yarn

Both can be installed via homebrew on Mac OS or via the downloads on Windows.

To install, navigate to this directory on your computer using the command line and run the following

yarn
npm install -g gatsby-cli

This will install Gatsby and all dependencies required. To run the site locally with live updates when content (MDX or RAML or others) is changed, run the following:

gatsby develop

Working with the site

In gatsby, all content is in the /src directory. In our gatsby site, this contains the following important subdirectories:

• /api-specs: This is where all RAML API specifications exist, for documentation generation purposes. The RAML specs are imported and should not be directly edited in this repository! For more information, see the API Specs README.
  • /api-specs/test: Contains the test specification. The test specification documents all RAML patterns that generate valid API documentation. Other modeling patterns will generally result in unsatisfactory results.
• /components: Contains the RAML-to-API doc components.
• /images: Images for any MDX pages.
• /pages/import: Individual pages (MDX files) containing content for the Import API.
• /pages/test-api: Contains pages which render out the test spec. Not generated on production builds.

All MDX-rendered content should be in the /src/pages directory. Pages use a .mdx file format, which is essentially markdown with react components mixed in. For more information, see MDXJS.

API Doc React components

By and large, the Import API doesn't have much actual content, instead containing component declarations like this:

## ImportSink

<ApiType apiKey="import" type="ImportSink" />

The Import API documentation is auto-generated based on the RAML using a set of custom-built components. This allows us as an organization to ensure standardized display of documentation information, keep description text in sync between the SDKs and the docs, and generally standardize our API documentation practice more.

Currently, the following components are available. By default, all props are required.

<ApiType>

Represents an individual API type representation – for example, a Cart, or an Order, or a PaymentDraft, or an AttributeDefinition. Each <ApiType> renders one type defined under the types section of a RAML API specification.

The declaration for an API type is as follows:

<ApiType apiKey="key" type="typeName" />

Prop	Description
apiKey	[String] Indicates which API spec to look for the type declaration in. The key is defined by the directory name the RAML file is in when imported to the docs project. If multiple RAML files exist in the same directory, they all share the same key.
type	[String] The name of the type as defined in the RAML file. If the type does not exist, the site build will break.

<ApiEndpoint>

Represents an endpoint, or an API relative URI and HTTP method, such as Get All Carts or Create a cart. Each <ApiEndpoint> renders one HTTP method as defined for a particular URI in the endpoints section of a RAML reference.

The declaration for an API type is as follows:

<ApiEndpoint apiKey="test" resource="/{projectKey}/resource"  method="POST" />

Prop	Description
apiKey	[String] Indicates which API spec to look for the type declaration in. The key is defined by the directory name the RAML file is in when imported to the docs project. If multiple RAML files exist in the same directory, they all share the same key.
resource	The path to the resource, as defined in the RAML.
method	The HTTP method you wish to render.

License

The content - for example images, other media, designs, and text - of this project itself is UNLICENSED except internal usage at commercetools GmbH and its subsidiaries. Contact [e-mail] to inquire exceptions.

The underlying source code used to format and display that content is currently UNLICENSED except internal usage at commercetools GmbH and its subsidiaries. Contact [e-mail] to inquire exceptions.