neo-api-to-ts-interface_skill

Overview

This skill automates generation of TypeScript interfaces from REST API responses and produces a Storybook-style documentation UI for exploring the resulting types. It parses JSON or XML payloads, infers precise type shapes (including unions, optionals, arrays, and recursive structures), and emits validated, well-formatted .ts files. The Storybook output provides interactive, example-driven documentation for teams and CI pipelines.

How this skill works

The parser accepts JSON/XML strings or file paths and walks the payload recursively to build an internal type representation that captures primitives, objects, arrays, unions, nullable fields, and discriminants. The generator converts that representation into TypeScript interfaces using best-practice patterns (readonly, index signatures, union types), merges with reference type overrides, and validates syntax with the TypeScript compiler API. A Storybook renderer then generates Component Story Format artifacts and interactive pages that visualize nested structures with example values extracted from the responses.

When to use it

• You want to avoid manual interface authoring for rapidly evolving APIs
• Onboard new API endpoints into a TypeScript codebase with accurate types fast
• Create searchable, example-driven documentation for API response shapes
• Integrate into CI to ensure generated types remain in sync with sample responses

Best practices

• Provide representative sample responses (success, error, edge cases) to improve inference accuracy
• Use project-level .apitotsrc.json to standardize output paths and template choices
• Maintain a types.json with overrides for common or external domain types to avoid duplicates
• Run the validate command in CI to catch syntax or typing regressions before merge

Example use cases

• Generate a single interface file from an API response with the CLI for a new endpoint
• Batch-process multiple responses and either merge shared structures or emit separate interfaces
• Auto-generate Storybook docs for a contract review or API design meeting
• Embed into an agent workflow to auto-create interfaces from captured API traffic