schema2dts

A very simple JSONSchema7/OpenAPI3 to TypeScript types definitions generator

Usage no npm install needed!

<script type="module">
  import schema2dts from 'https://cdn.skypack.dev/schema2dts';
</script>

README

schema2dts

A very simple JSONSchema7/OpenAPI3 to TypeScript types definitions generator

Build status Coverage Status

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 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 { readFileSync, writeFileSync } from 'fs';
import {
  generateJSONSchemaTypes,
  generateOpenAPITypes,
  toSource,
} from 'schema2dts';

// Open API
const openAPISchema = JSON.parse(readFileSync('openapi.json').toString());

writeFileSync('API.d.ts', toSource(await generateOpenAPITypes(openAPISchema)));

// JSON Schema
const jsonSchema = JSON.parse(readFileSync('schema.json').toString());

writeFileSync('API.d.ts', toSource(await generateJSONSchemaTypes(jsonSchema)));

If you find some case 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"] }
  ]
}

Authors

License

ISC