Diagnostics

Building and rendering an API document never fails silently. Each finding is a SpecDiagnostic:

interface SpecDiagnostic {
  code: string;
  severity: "error" | "warning" | "info";
  message: string;
  pointer?: string; // a JSON Pointer into the model or the document
}

defineApi(...).diagnostics holds the findings from building the model, and every render result's diagnostics adds the ones from that render. The list has no duplicates. createOpenApi, createAsyncApi and createArazzo throw on any error and pass the rest to onDiagnostic. Match on code; the message text can change.

The overlay codes are on the overlay page.

Building the modelCopy Anchor Link

RenderingCopy Anchor Link

Checks on the finished documentCopy Anchor Link

These run last, after transform and overlays, so they also catch what those broke.

AsyncAPICopy Anchor Link

asyncapiFormat reports these while it renders the events, channels, messages and webhooks of the model.

These checks run on the finished document, after transform and overlays:

ArazzoCopy Anchor Link

arazzoFormat reports these while it renders the model's workflows.

These checks run on the finished document, after transform and overlays:

Fail a build on errorsCopy Anchor Link

const { document, diagnostics } = api.openapi({ version: "3.1" });

const errors = diagnostics.filter(
  (diagnostic) => diagnostic.severity === "error",
);
if (errors.length > 0) {
  for (const error of errors)
    console.error(`${error.code}: ${error.message} ${error.pointer ?? ""}`);
  process.exit(1);
}