Skip to content

README.md

Latest commit

 

History

History
185 lines (125 loc) · 9 KB

README.md

File metadata and controls

185 lines (125 loc) · 9 KB

SpectaQL configuration

This directory contains SpectaQL configuration files for generating the Merchandising GraphQL API reference as a static HTML page.

Prerequisites

  • Node.js matching the version in .nvmrc
  • Yarn

Files overview

Configuration and data files (spectaql/)

File Role
config-merchandising.yml Main SpectaQL config. Defines where to get the schema, what to document/hide, metadata paths, server info, intro text, theme, and the output directory (static/graphql-api/merchandising-api).
metadata-merchandising.json Filtering and description metadata. Marks unwanted queries, types, enums, unions, input objects, and interfaces as undocumented: true so SpectaQL excludes them. Also contains custom descriptions for query arguments under FIELD_ARGUMENT.
enhanced-schema.json Cached introspection result with custom descriptions already injected. Used for dev builds instead of hitting the live endpoint on every rebuild. Generated by scripts/fetch-and-enhance-schema.js.
config-merchandising-temp.yml Auto-generated temp config. A copy of the main config with ${TENANT_ID} placeholders replaced by the actual environment variable value. Deleted automatically after the build.
config-admin.yml Configuration for the Admin API (reference not currently implemented).
comdox-theme/ Custom SpectaQL theme. Contains Handlebars partial overrides (type.hbs and _query-or-mutation-or-subscription.hbs) that customize how types and queries render in the HTML output.

Build scripts (scripts/)

Script Role
generate-spectaql-config.js Reads config-merchandising.yml, substitutes ${TENANT_ID} from your .env file, writes the temp config, and cleans up on exit.
run-spectaql-with-cleanup.js Orchestrates the dev build: generates the temp config, switches it to use enhanced-schema.json, spawns SpectaQL as a child process, then cleans up the temp file. This is what yarn dev:merchandising-api runs.
fetch-and-enhance-schema.js Fetches a live introspection result from the GraphQL endpoint, then injects custom descriptions from metadata-merchandising.json into the raw schema. Saves the result to enhanced-schema.json.
build-with-enhanced-schema.js Orchestrates the production build: (1) fetches a fresh schema and injects descriptions from metadata-merchandising.json, (2) generates the temp config and rewrites it to point at enhanced-schema.json instead of the live URL, (3) runs SpectaQL. This is what yarn build:merchandising-api runs.

Environment and output

File Role
.env (root) Provides TENANT_ID and CATALOG_VIEW_ID needed to call the live GraphQL endpoint and substitute into the config.
static/graphql-api/merchandising-api/index.html The final output. The generated HTML documentation page that gets committed and embedded in the documentation site.

Environment variables

Set the following in a .env file in the project root:

cp .env.example .env
Variable Description
TENANT_ID Your Adobe Commerce tenant ID
CATALOG_VIEW_ID Catalog view ID for the API context

Both variables are required for any build that fetches the live schema.

How it works

The documentation is generated by SpectaQL, which turns a GraphQL schema into a static HTML API reference. The metadata-merchandising.json file does double duty: it both filters what appears (via undocumented: true markers) and provides custom descriptions (via the FIELD_ARGUMENT section and description fields on types/queries).

Documented queries

The metadata file includes only these queries:

  • attributeMetadata
  • categoryTree
  • navigation
  • productSearch
  • products
  • recommendationsByUnitIds
  • refineProduct
  • variants

All other queries and their exclusively-referenced types are marked as undocumented and excluded from the generated output.

Metadata file structure

The metadata file uses SpectaQL's metadata format with these sections:

  • OBJECT.Query.fields — Marks unwanted queries as undocumented: true
  • OBJECT.* — Marks unwanted Object types as undocumented: true
  • INPUT_OBJECT.* — Marks unwanted Input types as undocumented: true
  • ENUM.* — Marks unwanted Enum types as undocumented: true
  • UNION.* — Marks unwanted Union types as undocumented: true
  • INTERFACE.* — Marks unwanted Interface types as undocumented: true
  • FIELD_ARGUMENT — Provides custom descriptions for query arguments (e.g., categoryTree and navigation arguments)

Choosing the schema source

The config-merchandising.yml file supports two mutually exclusive schema sources under the introspection: section. Only one should be active at a time.

Live endpoint (default)

By default, the config uses the live GraphQL endpoint. This requires the TENANT_ID and CATALOG_VIEW_ID environment variables to be set in your .env file:

  # introspectionFile: spectaql/enhanced-schema.json
  url: https://na1-qa.api.commerce.adobe.com/${TENANT_ID}/graphql

Static schema file

To generate documentation offline without hitting the live endpoint, comment out the url line and uncomment the introspectionFile line:

  introspectionFile: spectaql/enhanced-schema.json
  # url: https://na1-qa.api.commerce.adobe.com/${TENANT_ID}/graphql

The static schema file (enhanced-schema.json) is a cached introspection result with custom descriptions already injected. You can update it at any time by running:

node scripts/fetch-and-enhance-schema.js

Note: Only one of url or introspectionFile should be uncommented. If both are active, SpectaQL will raise an error.

Build commands

Both build paths produce static/graphql-api/merchandising-api/index.html.

Production build

Fetches a fresh schema from the live endpoint, injects all custom descriptions from metadata-merchandising.json, and runs SpectaQL:

yarn build:merchandising-api

What happens during a production build:

  1. fetch-and-enhance-schema.js fetches the live introspection result and injects descriptions from metadata-merchandising.json directly into the schema JSON.
  2. The result is saved to enhanced-schema.json.
  3. generate-spectaql-config.js reads the YAML config, replaces ${TENANT_ID}, and writes the temp config.
  4. The temp config is rewritten to use introspectionFile: spectaql/enhanced-schema.json instead of the live URL.
  5. SpectaQL runs against the local enhanced schema file.
  6. The custom theme partials override the default rendering.
  7. Output lands in static/graphql-api/merchandising-api/index.html.
  8. The temp config file is cleaned up.

Dev build (fast iteration)

Uses the existing enhanced-schema.json on disk — no live API call. Useful when iterating on metadata descriptions, theme templates, or config without waiting for a schema fetch:

yarn dev:merchandising-api

This starts SpectaQL in watch mode with a live preview at http://localhost:4400. It rebuilds automatically when source files change.

Note: The dev build does not refresh enhanced-schema.json. If the live schema has changed or you have updated metadata-merchandising.json, run yarn build:merchandising-api to get a fresh result.

Update the cached schema only

To fetch and enhance the schema without running SpectaQL:

node scripts/fetch-and-enhance-schema.js

This saves the result to enhanced-schema.json and is useful when you want to inspect the schema before building.

Update the API reference

If the schema or metadata descriptions change, rebuild and test the API reference locally:

  1. Create a branch from main.

  2. Make your changes to metadata-merchandising.json, theme templates, or config.

  3. Run the production build to regenerate the schema and documentation:

    yarn build:merchandising-api

  4. Open static/graphql-api/merchandising-api/index.html in your browser and verify the output.

  5. Commit the updated index.html and enhanced-schema.json files.

  6. After updates are approved, a documentation team member merges the PR and publishes the updates to the developer site.

Generated output

The build generates static/graphql-api/merchandising-api/index.html, which is embedded in the documentation site using the Adobe I/O theme's frameSrc feature.

Notes

  • The ${TENANT_ID} placeholder in the YAML config is processed by scripts/generate-spectaql-config.js, which creates a temporary config-merchandising-temp.yml file
  • Temporary config files are automatically cleaned up after the build completes
  • The .env file is in .gitignore to prevent committing sensitive information
  • The Sass @import deprecation warnings during the build are cosmetic (from SpectaQL's internal stylesheets) and do not affect the output