README
¶
generator/typescript
generator/typescript renders OpenAPI component schemas as TypeScript type
declarations. It is a library package: no CLI, no client, no runtime code.
file, err := typescript.RenderSchemas(model.Model.Components.Schemas)
if err != nil {
return err
}
os.WriteFile("api.gen.ts", file.Source, 0o644)
RenderSchemas returns a *GeneratedFile with the module Source, the
exported Types in declaration order, and Diagnostics.
The output is a type-only module, so it erases entirely when compiled or run
with type stripping (node --experimental-strip-types). Shaping comes from the
same IR as generator/golang (golang.Generator.SchemaIRs), so both targets
read a schema the same way.
Mapping
| OpenAPI | TypeScript |
|---|---|
| object with properties | export interface X { … } at the top level, an inline { … } literal when nested |
| required / optional | name: T / name?: T |
nullable: true, type: [T, "null"] |
T | null; a 3.1 enum or const that leaves out null excludes it |
enum |
string, number or boolean literal union; never a TypeScript enum |
const |
literal type |
allOf |
intersection of referenced members and one literal of the merged inline members, properties declared beside allOf, and required names (undeclared ones as required unknown members, which makes an inherited property required) |
oneOf / anyOf |
union |
properties / required beside oneOf / anyOf |
an object literal intersected with the whole union; required names the outer schema does not declare become required unknown members |
oneOf with a discriminator |
each referenced variant that declares the discriminator inline as a plain string, integer or number is intersected with its literal values — the component name, which OpenAPI falls back to, plus any mapped values — so the union narrows; variants that declare it as a literal already narrow, and inherited or $ref-typed properties are left as they are |
additionalProperties: {schema} with no properties |
{ [key: string]: T }, which unlike Record may refer to its own type, so recursive maps compile |
additionalProperties: true or a schema, with properties |
[key: string]: unknown index signature |
patternProperties |
[key: string]: unknown index signature, even with additionalProperties: false |
required names with no declared property |
required members, typed by the additionalProperties schema when there is one (with a matching index signature if nothing else is declared), unknown otherwise |
type: object with no properties or required names |
{ [key: string]: unknown }, or { [key: string]: never } with additionalProperties: false |
items |
T[] |
prefixItems |
tuple of optional positions, [A?, B?, ...T[]]: items types the rest, items: false closes it, no items leaves it unknown |
| no type | unknown |
$ref to a component |
the component's type name |
$ref into a component (…/properties/p, /items, /additionalProperties) |
the type of the schema the pointer names, rendered in place |
description, deprecated |
JSDoc, @deprecated |
string formats, int64 |
string, number |
Component names are kept verbatim when they are valid TypeScript identifiers.
Names tsc rejects for a type declaration (reserved words such as await
and as, and predefined types such as string), invalid identifiers, and
Array, which the output uses, are renamed and reported with
invalidTypeScriptIdentifier. Valid names are claimed before renamed ones, so
a rename that lands on a taken name gets a suffix and a
componentNameCollision diagnostic. WithTypeNameResolver overrides naming,
and WithHeaderComment replaces the generated-code header.
A nested schema that cannot be built renders as unknown and is reported with
childSchema, as is a $ref pointer the generator cannot follow with
unsupportedPointerReference.
Known limitations
From the shared IR, which the Go target also has:
- A nullable
oneOf: [$ref, null]takes the referenced schema's description rather than its own, and drops properties or required names declared beside it. - A multi-type schema such as
type: [array, object]renders as a union of the bare types, without itsitemsorproperties.
From TypeScript or this generator's choices:
readOnlyandwriteOnlyare not modelled, so one type serves requests and responses: a requiredreadOnlyproperty is required in request bodies too.additionalPropertiesbesideallOfis ignored.- Pointers through
allOf/N,oneOf/NoranyOf/Nrender asunknown. - Non-scalar
constvalues, and YAML numbers that are not JSON numbers (such as0x1For.inf), render asunknown. - Integer and number are both
number, and string formats are not checked. - A schema with
propertiesoritemsbut notypeis treated as an object or array, although JSON Schema also accepts other values there. - An optional property named after a member of
Object(constructor,toString,valueOf) makes{}unassignable, because TypeScript checks the missing key againstObject's own member. - External
$refs render as the referenced name without declaring it; bundle the document first.
Documentation
¶
Overview ¶
Package typescript generates TypeScript type declarations from OpenAPI schemas.
The package is library-only and emits types, never runtime code: the output is a type-only module of interfaces and type aliases, so it erases completely when compiled or when TypeScript is run with type stripping. Enums therefore render as string-literal unions rather than TypeScript enum declarations.
Schema shaping is shared with the Go model generator: Generator.RenderSchemas asks the golang package for its language-neutral IR (see golang.Generator.SchemaIRs) and prints TypeScript from it. Component schema names are kept verbatim when they are valid TypeScript identifiers, so generated names match the names used in the OpenAPI document. Nested inline schemas render as inline type literals rather than as separate named declarations.
Index ¶
Constants ¶
const ( // DiagnosticInvalidIdentifier reports a component name that is not a valid // TypeScript type identifier and was renamed. DiagnosticInvalidIdentifier = "invalidTypeScriptIdentifier" // DiagnosticExternalReference reports a $ref outside the document's // components, rendered by the name of its final path segment. DiagnosticExternalReference = "externalReference" // DiagnosticUnsupportedPointer reports a $ref into a component through a // keyword that has no TypeScript indexed-access equivalent. DiagnosticUnsupportedPointer = "unsupportedPointerReference" )
Diagnostic codes reported by the TypeScript generator in addition to the shared golang IR codes.
const DefaultHeaderComment = "Code generated by libopenapi. DO NOT EDIT."
DefaultHeaderComment is the header written at the top of every generated file unless WithHeaderComment replaces it.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Diagnostic ¶
type Diagnostic = golang.Diagnostic
Diagnostic describes a notable generator decision. It is the same type the golang generator reports, so callers can handle both uniformly.
type GeneratedFile ¶
type GeneratedFile struct {
// Source is the complete module text.
Source []byte
// Types lists the exported type names in declaration order.
Types []string
// Diagnostics reports naming decisions, pointers and schema keywords that
// could not be rendered exactly, and nested schemas that could not be built.
Diagnostics []Diagnostic
}
GeneratedFile is one TypeScript module rendered from a set of schemas.
func RenderSchemas ¶
func RenderSchemas(schemas *orderedmap.Map[string, *highbase.SchemaProxy], opts ...Option) (*GeneratedFile, error)
RenderSchemas renders an ordered map of component schemas, such as Components.Schemas of a v3 document, as one TypeScript module.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator holds immutable TypeScript generation configuration. It is safe to reuse across documents and goroutines.
func NewGenerator ¶
NewGenerator creates a TypeScript model generator.
func (*Generator) RenderSchemas ¶
func (g *Generator) RenderSchemas(schemas *orderedmap.Map[string, *highbase.SchemaProxy]) (*GeneratedFile, error)
RenderSchemas renders an ordered map of component schemas as one TypeScript module, declaring one exported type per schema in input order.
type NameResolver ¶
NameResolver maps an OpenAPI component name to a TypeScript type name. Returning an empty string keeps the default naming.
type Option ¶
type Option func(*Generator)
Option configures a Generator.
func WithHeaderComment ¶
WithHeaderComment replaces DefaultHeaderComment. Each line is written as a `//` comment. An empty string omits the header.
func WithTypeNameResolver ¶
func WithTypeNameResolver(resolver NameResolver) Option
WithTypeNameResolver sets the mapping from component names to TypeScript type names.
Source Files