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:
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 support@commercetools.com 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 support@commercetools.com to inquire exceptions.