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/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>;

Notes

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

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"]).	-
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

Todo

• Explore ability to import dereferenced schemas instead of inlining
• 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

Changelog

0.2.0

Minor Changes

• 56cf900: OpenAPI parameters get converted only when found in the places dictated by the specs (paths[path].parameters and paths[path][operation].parameters)
• 1543d34: Preserve commented $ref property in deferenced schemas
• d4395ea: Resolve external and public remote $refs

Patch Changes

• d3d5fa5: Convert deeply nested OpenAPI definitions