openapi-operation

Static OpenAPI operation reference

Install

docsloth component add @docsloth/openapi-operation@1.0.0

Live package: sha256:0d07bbe12d9741605cc6552c81ff01c845a98de7aaec18b91aa912e1728ec559 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

Props

The prop schema is normative in packages/contracts/component-props/openapi-operation.schema.json.

Example props generated from this schema:

{
  "operationId": "getPet",
  "method": "GET",
  "path": "/v1/pets",
  "summary": "Retrieve a pet",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "required": true,
      "description": "Max items",
      "example": 10
    }
  ],
  "responses": [
    {
      "status": 200,
      "description": "A pet"
    }
  ]
}

Required props: operationId, method, path, summary.

Example

Example document IR (the block the renderer consumes):

{
  "type": "openapi-operation",
  "props": {
    "operationId": "getPet",
    "method": "GET",
    "path": "/pets/{petId}",
    "summary": "Retrieve a pet",
    "parameters": [
      {
        "name": "petId",
        "in": "path",
        "required": true,
        "description": "Pet id",
        "example": "42"
      }
    ],
    "responses": [
      {
        "status": 200,
        "description": "A pet"
      },
      {
        "status": 404,
        "description": "Not found"
      }
    ]
  }
}

Renderer HTML (entities decoded and wrapped for display):

<section class="ds-operation" data-component="openapi-operation" data-operation-id="getPet" aria-label="GET /pets/{petId} operation">
<p class="ds-operation-signature">
<span class="ds-method" data-method="GET">GET</span>
<code class="ds-operation-path">/pets/{petId}</code>
</p>
<p class="ds-operation-summary">Retrieve a pet</p>
<table class="ds-operation-params">
<thead>
<tr>
<th>name</th>
<th>in</th>
<th>required</th>
<th>description</th>
<th>example</th>
</tr>
</thead>
<tbody>
<tr>
<td>petId</td>
<td>path</td>
<td>yes</td>
<td>Pet id</td>
<td>42</td>
</tr>
</tbody>
</table>
<table class="ds-operation-responses">
<thead>
<tr>
<th>status</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>A pet</td>
</tr>
<tr>
<td>404</td>
<td>Not found</td>
</tr>
</tbody>
</table>
<pre class="ds-operation-example" aria-label="Example request">
<code>GET /pets/{petId}</code>
</pre>
</section>

Preview (interface-only; the markup above is the same output):

GET /pets/{petId}

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

Specification

Generated from packages/contracts/component-specs/openapi-operation.md.

Contract

Packaged: this block ships as @docsloth/openapi-operation@1.0.0 — an installable component package (kind block, capability render.html, Apache-2.0) whose production props schema is packages/contracts/component-props/openapi-operation.schema.json and whose catalog entry is in packages/contracts/component-catalog.json. No protocol manifest fixture is published (manifest_fixture: null): the fixture models a packaged protocol runtime this block does not have.

Intended behavior

Render one static OpenAPI operation — the counterpart the core can generate from a spec — as a readable card: method badge, path, summary, parameter table and response table. Because it is props-driven it needs no network, spec fetch or schema resolution at render time, and the Markdown twin carries the same tables plus an http example so agents can reconstruct the operation without parsing HTML.

Failure and fallback

A missing operationId/summary/method/path, a non-array parameters/responses, a parameter without a name or a response without a status degrades the block to the labelled fallback. An operation with no parameters or responses is valid and simply omits those tables. Unknown extra props are ignored.

Required acceptance cases

Rendering the same operation twice must produce identical output (no clock, no random ids, no fetches), and the Markdown twin must name every parameter and response the HTML shows. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

Native renderer block

packages/renderer renders an openapi-operation block as a <section data-operation-id="…"> with a method badge (data-method), the path, the summary, a parameters table (name, in, required, description, example), a responses table (status, description) and an example request line. Markdown emits the same signature, summary and tables, then the same request as a fenced http example. All content is static and escaped; nothing is fetched or executed.

Native block props

Example

{
  "type": "openapi-operation",
  "props": {
    "operationId": "getPet",
    "method": "GET",
    "path": "/pets/{petId}",
    "summary": "Retrieve a pet",
    "parameters": [{ "name": "petId", "in": "path", "required": true, "description": "Pet id", "example": "42" }],
    "responses": [{ "status": 200, "description": "A pet" }, { "status": 404, "description": "Not found" }]
  }
}

Package manifest

No protocol fixture is published for this renderer-native block.

Sources