Operation components

Use the operation components to connect a guide, tutorial, or changelog to the full API reference. They share Speccy's method badges, paths, color modes, and code presentation.

In a React app, import them from the renderer's documentation entry point:

import {
  EndpointStrip,
  OperationCard,
  OperationLink,
  OperationPreview,
} from 'speccy-renderer/docs';
import 'speccy-renderer/styles.css';

In Docusaurus MDX, import the same components from the plugin's client entry point. Registering the plugin already loads their styles:

import {
  EndpointStrip,
  OperationCard,
  OperationLink,
  OperationPreview,
} from 'docusaurus-plugin-speccy/client';

Inline link

OperationLink fits inside a sentence when the operation is part of an instruction.

Call POST/orchards to register an orchard.

<p>
  Call{' '}
  <OperationLink method="post" path="/orchards" href="/api/createorchard" /> to
  register an orchard.
</p>

Endpoint strip

EndpointStrip makes the operation the next step in a guide.

GET/orchards/{orchardId}Open reference

<EndpointStrip
  method="get"
  path="/orchards/{orchardId}"
  href="/api/getorchard"
/>

Operation card

OperationCard adds a summary and optional description. Use cards when readers need to choose from a small collection of related operations.

POST/orchardsCreate an orchardRegister an orchard and its initial growing blocks.View operation

<OperationCard
  method="post"
  path="/orchards"
  summary="Create an orchard"
  description="Register an orchard and its initial growing blocks."
  href="/api/createorchard"
/>

Operation preview

OperationPreview puts a layered request and optional response beside an operation link. The request always shows its path, then adds query parameters, headers, and a body when they exist. Query parameters and headers start collapsed; readers can open any section or copy it separately. When a response is available, readers can switch between request and response tabs.

POST/orchardsOpen API reference

/orchards

{  "name": "Nightingale Farm",  "region": "kent"}

Derive examples from an OpenAPI document

Pass the OpenAPI document through spec to find the operation by its method and path. spec accepts a parsed OpenAPI object or a JSON or YAML string. When spec is present, href is derived from the operation as well (see Resolve operations from your OpenAPI document).

import spec from './openapi.json';

<OperationPreview method="post" path="/orchards" spec={spec} />;

The derived request uses the first declared media type. Path parameter values are substituted into the displayed path. Query parameters, headers, and the body appear as separate sections only when the operation defines them.

The derived response uses the first 2xx response, or the first declared response if the operation has no successful response. For request and response bodies, Speccy checks media-type example, named examples, schema examples, defaults, and enums before generating a value from the schema.

Override a derived example

Use requestValues when a guide needs values that differ from the reusable examples in the API description. Overrides merge with derived values by section, so you can change one path parameter or header without repeating the rest of the request.

<OperationPreview
  method="post"
  path="/orchards"
  href="/api/createorchard"
  spec={spec}
  requestValues={{
    query: { dryRun: true },
    headers: { 'X-Tenant-ID': 'tenant_456' },
    body: { name: 'My orchard' },
  }}
/>

The available request sections are path, query, headers, and body:

<OperationPreview
  method="get"
  path="/orchards/{orchardId}"
  href="/api/getorchard"
  spec={spec}
  requestValues={{
    path: { orchardId: 'orch_01J7' },
    query: { expand: 'growingBlocks' },
    headers: { 'X-Tenant-ID': 'tenant_456' },
  }}
/>

requestExample remains available as a shorthand body override. responseExample overrides the derived response. Both accept a formatted string or a plain object, which is printed as indented JSON. These explicit values don't affect the other side of the preview.

Configure one or both sides

You don't need a spec when supplying values directly. Pass a body and response for a tabbed preview:

<OperationPreview
  method="post"
  path="/orchards"
  href="/api/createorchard"
  requestExample={'{\n  "name": "Nightingale Farm"\n}'}
  responseExample={'{\n  "id": "orch_01J7"\n}'}
/>

For a request without a body, pass structured values alone. The path is always rendered:

<OperationPreview
  method="delete"
  path="/orchards/{orchardId}"
  href="/api/deleteorchard"
  requestValues={{ path: { orchardId: 'orch_01J7' } }}
/>

If no spec or request values are supplied, the request preview contains the unresolved path. If neither an explicit nor derived response exists, the response tab is omitted.

Set section disclosure defaults

Use defaultCollapsed to change the initial state of any section. Its keys are path, query, headers, and body; unspecified keys retain their defaults. By default, query and headers are collapsed, while path and body are open.

<OperationPreview
  method="post"
  path="/orchards/{orchardId}"
  href="/api/updateorchard"
  requestValues={{
    path: { orchardId: 'orch_01J7' },
    query: { dryRun: true },
    headers: { 'X-Tenant-ID': 'tenant_456' },
    body: { name: 'Nightingale Farm' },
  }}
  defaultCollapsed={{ path: true, query: false, headers: false, body: true }}
/>

Preview props

Prop	Required	Purpose
`method`	Yes*	HTTP method used for the badge and operation lookup.
`path`	Yes*	OpenAPI path used for display and operation lookup. May end in a `#variant` fragment to pick between variants.
`operationId`	No	Looks the operation up by id instead of by method and path. `method` and `path` become optional.
`href`	No	Link to the full operation reference. Derived from the operation when a spec is available.
`spec`	No	OpenAPI object, JSON string, or YAML string used to derive `href`, request values, and a response.
`basePath`	No	Route where the reference for `spec` is mounted. Defaults to `/api`.
`api`	No	Name of the provider source to look the operation up in.
`requestValues`	No	Structured `path`, `query`, `headers`, and `body` values merged over values derived from spec.
`requestExample`	No	Request body string or object. Overrides a body supplied by `spec` or `requestValues`.
`responseExample`	No	Explicit response string or object. Overrides a response derived from `spec`.
`defaultCollapsed`	No	Initial collapsed state by section: `path`, `query`, `headers`, or `body`. Query and headers default to collapsed.
`theme`	No	`inherit` (default), `light`, `dark`, or `system`. `inherit` follows the host page's theme, including Docusaurus dark mode.
`className`	No	Adds a class without replacing Speccy's component classes.
`onClick`	No	Lets a host intercept clicks on the full operation reference link.

* Either method and path, or operationId, must be given.

Resolve operations from your OpenAPI document

Every component can derive href from the operation's operationId, and OperationPreview can derive its examples, once it can see the OpenAPI document. Pass spec (and basePath when the reference is not mounted at /api) to a single component, or wrap a page or your whole app in OperationReferenceProvider so no usage repeats the document:

import { OperationReferenceProvider } from 'speccy-renderer/docs';
import spec from './openapi.json';

<OperationReferenceProvider spec={spec} basePath="/api">
  <p>
    Call <OperationLink method="post" path="/orchards" /> to register an
    orchard.
  </p>
  <OperationPreview method="get" path="/orchards/{orchardId}" />
</OperationReferenceProvider>;

In Docusaurus, use SpeccyOperationReferenceProvider in src/theme/Root.tsx. It reads the compact operation catalogs generated by every configured Speccy plugin instance, so the site does not bundle or parse complete OpenAPI documents on every documentation page:

src/theme/Root.tsx
import { SpeccyOperationReferenceProvider } from 'docusaurus-plugin-speccy/client';

export default function Root({ children }) {
  return (
    <SpeccyOperationReferenceProvider>
      {children}
    </SpeccyOperationReferenceProvider>
  );
}

Each catalog uses the plugin instance id as its API name. Pass that name through api when an operation exists in several references.

Links use the operation route that the Docusaurus plugin and Speccy generate: the slugified operationId beneath basePath. Pass operationSegment on a source when your reference nests operations under an extra segment such as /operations.

Several APIs

Give the provider a list of sources when your site documents more than one API. Components search the sources in order and use the first operation that matches. Name the sources and pass api when two APIs share a path:

<OperationReferenceProvider
  apis={[
    { name: 'multi', spec: multi, basePath: '/api' },
    { name: 'backoffice', spec: backoffice, basePath: '/api/backoffice' },
  ]}
>
  <EndpointStrip method="post" path="/access_token" api="backoffice" />
</OperationReferenceProvider>

Path variants and operation ids

Some documents declare several operations for the same method and path with a #variant suffix, such as /managed_cards#prepaid and /managed_cards#debit. Pass the full key as path to pick one; the fragment never appears in the rendered path.

When the displayed path should differ from the OpenAPI path - a concrete value instead of a placeholder, or a shorter form - look the operation up by operationId and keep path for display:

<OperationPreview
  method="post"
  path="/orchards/{orchardId}/harvests/2024"
  operationId="createHarvest"
/>

operationId also finds webhooks, so <OperationLink operationId="fruitShipped" /> links to a webhook page and shows its declared path.

Every component needs method and path, or an operationId. href is required only when no OpenAPI document is available to derive it from. OperationCard also requires summary. The other content is optional.

The strip, card, and preview include bottom spacing so following prose and code blocks do not sit flush against them. Override that spacing through className when a parent layout controls the gap.

The components render ordinary links. When you set href yourself, point it at the operation URL generated from its slugified operationId, and use onClick when your host needs to intercept navigation. className lets you add layout styles without replacing the Speccy treatment.

Inline link​

Endpoint strip​

Operation card​

Operation preview​

Derive examples from an OpenAPI document​

Override a derived example​

Configure one or both sides​

Set section disclosure defaults​

Preview props​

Resolve operations from your OpenAPI document​

Several APIs​

Path variants and operation ids​

Props and navigation​