ContextQMD
Back to Medusa

Medusa API Reference

www/apps/api-reference/README.md

2.19.01.6 KB
Original Source

Medusa API Reference

The Medusa API Reference website is built with Next.js 13. You can learn more about contributing here.

Note About OpenAPI Specs

The OpenAPI Specs under the directory specs are automatically generated by our OAS CLI tool. So, contributions should be made in the files under packages/medusa/src/api instead of directly making changes to the generated spec files.

URL Structure

The reference uses real page paths (not hash anchors):

  • Area introduction: /api/{area} (e.g. /api/store)
  • Intro section: /api/{area}/{section} (e.g. /api/store/authentication)
  • Tag: /api/{area}/{tag} (e.g. /api/store/carts)
  • Operation: /api/{area}/{tag}/{operation} (e.g. /api/store/carts/get-a-cart)
  • Tag schema: /api/{area}/{tag}/schema

Paths are computed by shared helpers in packages/docs-utils (getApiRefTagSlug, getApiRefOperationSlug, getApiRefPath) and materialized into generated/api-ref-paths.mjs by scripts/prepare.mjs (yarn prep). That file also holds apiRefRedirects, an old-hash → new-path map used by the client-side HashRedirector (mounted on the area index) to redirect legacy #-anchor links.

The operation slug is derived from the operation's x-sidebar-summary (falling back to summary, then operationId). Because it's summary-derived, editing a summary can change the operation's URL. The redirect map is regenerated on every build to absorb such changes; set x-sidebar-summary on an operation to pin a stable slug. Slugs are de-duplicated within a tag (-2, -3, ...).