Openapi Toolkit

OpenAPI / Swagger REST API specification capability pack for backend developers, API designers and integrators: validate an OpenAPI 3 / Swagger spec (validate) and get a structured list of errors and...

openapi-toolkit

OpenAPI 3 / Swagger spec intelligence pack for API designers and integrators. Parses a spec from an object, a JSON string, or a YAML-ish string (built-in heuristic parser — no deps), then validates, diffs, lists, exemplifies, documents or builds specs. Deterministic cores; toMarkdown has an optional AI overview layer that falls back silently when no model is reachable.

Tools

Tool	Args	Does
`validate`	`{spec, options?}`	Structured `{valid, errors, warnings}` — missing version/info/paths/responses, dup operationIds, dangling `$ref`. `options.strict` adds style warnings.
`diff`	`{specA, specB}` (aliases `from`/`to`, `old`/`new`, `a`/`b`)	Added / removed / changed operations + a `breaking` list (removed ops, removed params/responses).
`listEndpoints`	`{spec}`	Every operation: method, path, operationId, summary, tags, params, responses.
`exampleRequest`	`{spec, method?, path?, operationId?, options?}`	A runnable `curl` + sample JSON body synthesized from the operation's schema. `options.baseUrl` overrides the server URL.
`toMarkdown`	`{spec, options?}`	Markdown API reference grouped by tag. `options.describe` adds an AI overview when a model is up.
`buildSpec`	`{endpoints:[{method,path,summary?,tags?,body?,responses?}], info?, options?}`	A minimal valid OpenAPI 3 spec (object + pretty JSON) from a compact endpoint list; infers path params and a body schema.

Example

import pack from './index.js';
const { spec } = pack.adapters.buildSpec({
  endpoints: [{ method: 'post', path: '/users', summary: 'Create user', body: { name: 'string', age: 0 } },
              { method: 'get', path: '/users/{id}', summary: 'Get user' }],
  info: { title: 'Users API', version: '1.0.0' },
});
pack.adapters.validate({ spec });                 // { valid: true, counts:{…} }
pack.adapters.exampleRequest({ spec, method: 'post', path: '/users' }); // { curl:"curl -X POST …", body:{…} }

DRY boundaries

schema owns JSON-Schema shapes (validate/generate a schema for a data object). This pack works

at the whole-API / route level — paths, operations, versions, curl examples, API reference. It reuses the JSON-Schema concept to synthesize example bodies but never imports schema.

Self-contained: only cross-pack import is ../_shared/llm.js.

Hybrid intelligence

All parsing/validation/diff/build cores run offline. Only toMarkdown (options.describe:true) reaches for an LLM to add a prose overview; with no model it returns the reference doc with mode:'heuristic'. A down model never throws.