openapi-typescript-validator

Generate typescript with ajv validation based on openapi schemas

What does this do?
Getting started
Documentation
- generate

What does this do?

This package will convert your openapi 3.0 spec to:

Typescript models
Decoders which validate your models against a JSON schema

Example

This schema (note: also works with JSON based schema's)

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required: ['id']

Will convert to:

export interface User {
  id: string;
  name?: string;
}

And will generate a decoder:

// user will be of type User if the JSON is valid
const user = UserDecoder.decode(json);

If the JSON is invalid, it will throw an error:

const user = UserDecoder.decode({
  id: 1
});

// User: /id: should be string. JSON: {"id":1}

References

References als work, this schema

{
  "components": {
    "schemas": {
      "Screen": {
        "type": "object",
        "properties": {
          "components": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Component" }
          }
        },
        "required": [ "components" ]
      },

      "Component": {
        "anyOf": [
          { "$ref": "#/components/schemas/TitleComponent" },
          { "$ref": "#/components/schemas/ImageComponent" }
        ]
      },

      "TitleComponent": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["title"]
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [ "type", "title" ]
      },

      "ImageComponent": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["image"]
          },
          "url": {
            "type": "string"
          }
        },
        "required": [ "type", "url" ]
      }
    }
  }
}

will generate

export type Component = TitleComponent | ImageComponent;

export interface Screen {
  components: Component[];
}
export interface TitleComponent {
  type: "title";
  title: string;
  subtitle?: string | null;
}
export interface ImageComponent {
  type: "image";
  url: string;
}

Custom builder

We also created a way to define your JSON schema a bit easier. The example above can also be written as:

Example: custom-schema.js

const { anyOf, array, constant, nillable, object, string } = require('openapi-typescript-validator');

const types = {};

types.Screen = object({
  components: array('Component'),
})

types.Component = anyOf(['TitleComponent', 'ImageComponent']);

types.TitleComponent = object({
  type: constant('title'),
  title: string,
  subtitle: nillable(string),
});

types.ImageComponent = object({
  type: constant('image'),
  url: string,
});

module.exports = { types }

Just call generate with schemaType: custom.

See src/builder.ts for all helpers which can be used.

Getting started

Install the package

npm i openapi-typescript-validator --save-dev

We use ajv for the decoders

npm i ajv

Your tsconfig.json file will need to be able to resolve the json files.

"resolveJsonModule": true

Create a node script called generate-schemas.js

const path = require('path');
const { generate } = require('openapi-typescript-validator');

generate({
  schemaFile: path.join(__dirname, 'myswagger.yaml'),
  schemaType: 'yaml',
  name: 'api',
  directory: path.join(__dirname, '/generated')
})

and run node generate-schemas.js

Documentation

generate

generate can be called with GenerateOptions

param	required	description
schemaFile	true	file location of the schema.
schemaType	true	`yaml`, `json` or `custom`
name	true	prefix for the generated files
directory	true	`string` or `string[]` location(s) where the output files will be stored.
prettierOptions	false	See Prettier Options

goodoldneon/openapi-typescript-validator