schema2dts

A very simple JSONSchema7/OpenAPI3 to TypeScript types definitions generator

It is intended to support JSONSchema7/OpenAPI3 but may work for some if not most
JSONSchema versions.

This module assumes your JSONSchema / OpenAPI3 documents are valid. It also
doesn’t support external references at the moment (and probably for ever) and
expect a single object whose definitions are all relative to the root object.

It is also meant to be a building block for higher level generators.

Usage

import { readFile, writeFile } from 'node:fs/promises';
import {
  generateJSONSchemaTypes,
  generateOpenAPITypes,
  toSource,
} from 'schema2dts';
// Open API
const openAPISchema = JSON.parse(readFileSync('openapi.json').toString());
await writeFile(
  'API.d.ts',
  toSource(await generateOpenAPITypes(openAPISchema)),
);
// JSON Schema
const jsonSchema = JSON.parse(readFileSync('schema.json').toString());
await writeFile(
  'API.d.ts',
  toSource(await generateJSONSchemaTypes(jsonSchema)),
);

If you find some cases with unexpected results, please add the fixtures to this
repository in a pull request and describe the problem you encounter.

Options

You can change the API main namespace in order to be able to use several
generated types in the same repository. Just provide its namespace a the second
argument to generateOpenAPITypes.

The third argument is for options:

• you can generate the unused schemas (especially useful when in development
  mode) to be able to use them in your code despite the fact they ain’t used in
  you API at that moment. Just set generateUnusedSchemas to true.
• you can also filter the statuses you wish to generate by setting
  filterStatuses to [200, 201, 202, 300] for example so that the 500 errors
  responses ain’t taken in count.

Known issues

There is some differences between the JSONSchema anyOf, allOf and oneOf
keywords (learn
more here on combining schemas).

The current way to handle this in this library is to:

• convert oneOf to an
  union type
  which is valid
• convert anyOf to an union type too which is not really what it means in JSON
  Schema
• convert allOf to an
  intersection type
  which is completly wrong and will work only with JSON Schemas meant to be used
  that way. By example, combining an existing object schema with another object
  to make some properties required will only work if you set its type to
  object in both schemas explicitly:

{
  "allOf": [
    {
      "$ref": "#/definitions/User"
    },
    { "type": "object", "required": ["id"] }
  ]
}

Currently, the if/then keywords of JSONSchema do not work. You should be
able to replace most of its use per a oneOf form.

API

Functions

generateOpenAPITypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from an Open API document

generateJSONSchemaTypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from a JSONSchema document

toSource(nodes) ⇒

Returns source from a list of TypeScript statements

generateOpenAPITypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from an Open API document

Kind: global function

generateJSONSchemaTypes(schema, options) ⇒ TypeScript.NodeArray

Create the TypeScript types declarations from a JSONSchema document

Kind: global function

toSource(nodes) ⇒

Returns source from a list of TypeScript statements

Kind: global function
Returns: string

Authors

• Nicolas Froidure

License

ISC