API artifacts and migration tooling

Use the installed project-local CLI. These commands operate on your application's API contracts; they do not publish UDIOT framework documentation.

Generate API documentation

npx --no-install udiot docs api --out build/openapi.json --api-version v1

--types includes TypeDoc output and --ai requests configured AI examples. --golden writes a canonical test/contracts/golden-openapi.v{n}.json. --export redoc|swaggerhub|html and --export-dir control rendered artifacts. Check your installed command's help and review generated specifications against actual controller behavior; metadata emission does not test an endpoint.

Compare contracts

npx --no-install udiot api compare baseline.json head.json --engine auto --format json --output build/api-report.json --fail-on-breaking

Inputs may be file paths or version tokens such as v1. Engines are simple, openapi-diff, pb33f and auto; the compare default is simple. Formats are summary, json, md and html. Use --strict where the openapi-diff path must fail closed instead of falling back. Inspect which engine actually produced the result; passing a coarse comparison is not a semantic compatibility proof.

Draft migration guidance

npx --no-install udiot api migrate baseline.json head.json --engine auto --out build/migration-review.md

The generated document is review material. Verify breaking changes, executable examples and application-specific rollout/rollback steps, then put maintained UDIOT guidance in the website's content/docs/. The framework workflow retains generated migration output as a build artifact rather than creating a second guide set under the framework's docs/.

SDK publication

udiot sdk publish <outDir> supports --registry npm|github, --name, --package-version and --dry-run. A dry run creates package metadata without publishing; normal publication changes the configured registry. Validate the generated SDK, package contents, version and credentials independently. This command is separate from framework publishing.