openapi-typescript-validator-ext-ref

Generate typescript with ajv validation based on openapi schemas

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
openapi-typescript-validator-ext-ref
3.2.0-external-ref-support6 months ago6 months agoMinified + gzip package size for openapi-typescript-validator-ext-ref in KB

Readme

openapi-typescript-validator
Generate typescript with ajv >= 8.0.0 validation based on openapi schemas
- 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',
  directory: path.join(__dirname, '/generated')
})

and run node generate-schemas.js
Note We recommened to setup your schema configuration in a different folder than your application. E.g:
  • schemas
- package.json which depends on this library
  • server
- package.json with ajv depedency and ajv-formats (if you use formats)

Breaking changes

upgrading to V3

When using the custom format for your schemas. The string, boolean, number, etc helpers are now a function instead of const.
You'll need to update your schemas
// v2
object({ title: string })

// v3:
object({ title: string() })

Documentation

generate

generate can be called with GenerateOptions. See the file for more info.