Generate TypeScript types from OpenAPI
OpenAPI can generate more reliable client types than one example response, but only when the contract is valid, specific, and treated as the source of truth.
Validate the contract first
Generation should fail on an invalid specification rather than producing partial or misleading types. Resolve broken references, missing required fields, duplicate operation identifiers, and unsupported schema combinations before updating generated code. Use the OpenAPI Validator for a quick structural check and keep your project’s full validator in CI.
Required is different from nullable
A required property must appear in the object. A nullable property may contain null. They are separate decisions: a field can be required and nullable, optional and non-null when present, both, or neither. Verify how the selected generator represents each combination, especially when migrating between OpenAPI versions.
Review unions, enums, and additional properties
oneOf, anyOf, discriminators, enums, and maps can produce very different TypeScript shapes between generators. An open object may become an index signature, while a closed object rejects unknown keys in the contract but not at TypeScript runtime. Test representative schemas before adopting generated output across a codebase.
Formats are not runtime objects
An OpenAPI string with format: date-time normally arrives over HTTP as a string. Generating a JavaScript Date type without a parsing layer can make the static type disagree with reality. The same caution applies to UUIDs, decimal values, binary data, and integers larger than JavaScript can represent safely.
Keep generation reproducible
Pin the generator version and keep one project command for local and CI use. Decide whether generated files are committed. If they are, CI can regenerate and fail when the working tree changes. If they are not, the build should generate them before type checking. Avoid manual edits to generated files; customize templates or add a separate wrapper layer.
Types are not validation
TypeScript disappears at runtime. A server can still return a payload that violates the contract. Validate untrusted responses at a boundary when correctness or security requires it, and monitor contract changes before regenerating clients. A clean compile does not prove wire compatibility.
Sample JSON has a different purpose
Cryonel’s JSON to TypeScript tool is useful when you only have a representative payload. It creates a starting interface but cannot infer optional fields, multiple status responses, constraints, or authentication. Prefer OpenAPI generation when a maintained contract exists.
Frequently Asked Questions
Are generated types runtime validation?
No. TypeScript types are erased at runtime and do not validate an HTTP response by themselves.
Should generated files be committed?
Either approach can work; choose one policy and make CI verify reproducible output.
Can I generate from one sample response?
A sample is useful for a draft but cannot describe the complete API contract.