openapi-ts-json-schema

openapi-ts-json-schema

Generate JSON schema TypeScript files (.ts) from OpenAPI definitions which can be natively used to infer types from (with json-schema-to-ts or fastify-type-provider-json-schema-to-ts).

Given an OpenAPI definition file, openapi-ts-json-schema will:

• Resolve external/remote $refs and dereference them with @apidevtools/json-schema-ref-parser (resolving $ref's)
• Convert to JSON schema with @openapi-contrib/openapi-schema-to-json-schema and openapi-jsonschema-parameters
• Generate one TypeScript JSON schema file for each definition (.ts files with as const assertion)
• Store schemas in a folder structure reflecting the original OpenAPI definition structure

Installation

npm i openapi-ts-json-schema -D

Usage

import { openapiToTsJsonSchema } from 'openapi-ts-json-schema';

const { outputPath } = await openapiToTsJsonSchema({
  openApiSchema: 'path/to/open-api-specs.yaml',
  definitionPathsToGenerateFrom: ['paths', 'components.schemas'],
});

...then in your code:

import Ajv from 'ajv';
import { FromSchema } from 'json-schema-to-ts';
import myModelSchema from 'path/to/schemas-autogenerated/components/schemas/MyModel.ts';

// Use generated JSON schemas as usual
const ajv = new Ajv();
const valid = ajv.validate(myModelSchema, { hello: 'World' });

// Use generated JSON schemas to infer model types from
type MyModel = FromSchema<typeof myModelSchema>;

Options

Property	Type	Description	Default
openApiSchema (required)	string	Path to the OpenApi file (supports yaml and json).	-
definitionPathsToGenerateFrom (required)	string[]	OpenApi definition object paths to generate the JSON schemas from. Only matching paths will be generated. (Supports dot notation: ["components.schemas"]).	-
experimentalImportRefs	boolean	Experimental option. Generate $ref schema files and import them instead of inlining.	false
schemaPatcher	(params: { schema: JSONSchema }) => void	Dynamically patch generated JSON schemas. The provided function will be invoked against every single JSON schema node.	-
outputPath	string	Path where the generated schemas will be saved. Defaults to /schemas-autogenerated in same directory as provided openApiSchema.	-
silent	boolean	Don't console.log user messages.	false

Notes

Generated JSON schema path names get escaped in order to be valid file system names.

Circular $refs can be technically resolved with experimentalImportRefs option. But TS will stop the type recursion and type the schema as any. See relevant tests.

Take a look at the Developer's notes for a few more in-depth explanations.

Todo

• Consider merging "operation" and "path" parameters definition
• Consider removing required definitionPathsToGenerateFrom option in favour of exporting the whole OpenAPI definitions based on the structure defined in specs
• Consider adding a way to keep specific $ref values in case of recursion

Changelog

0.3.0

Minor Changes

• 409c154: Handle circular $ref values.
• 8513db4: Add experimentalImportRefs option to generate and import $ref schema files istead of inlining.
• 7c61c0f: Generate nested folders instead of dotted path folders