# 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 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

```js
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.


---
Source: shared/engines/adapters/domain/openapi-toolkit/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/openapi-toolkit