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
transformerRaml
: See gatsby-transformer-raml 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
-> apiKeyfoo
src/api-specs/bar/api.raml
-> apiKeybar
src/api-specs/baz/baz.raml
-> apiKeybaz
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" />;