openapi-ts-typegen

Typescript type generator for OpenAPI specifications, generating types both for schemas and for all operations, with operation specific request parameters.

Installation

$ npm install @openapi-ts/typegen

Usage

To generate types for the OpenAPI specification my-api.yml and store them into src/gen/api:

$ npx @openapi-ts/typegen my-api.yml src/gen/api

The output directory will now contain various useful types corresponding to the OpenAPI specification:

Example type usage

The generated types includes all schemas from the API specification, as well as operation handlers for all operations, where each handler is a function on the form (req, res, params) => result and enables declaring a map of all operations with type-safe arguments, i.e., each operation will be passed a req argument which is typed for that operation.

This assumes that some framework is used to validate requests against the OpenAPI specification before invoking the operation handlers, e.g. AWS API Gateway or openapi-ts-backend

import * as MyApi from '.'; // generated directory

// Schema usage
const person: MyApi.Schemas['Person'] = {name: 'John Doe'};

// Custom params/context to pass to each operation
type MyParams = { context: {foo: string;}; };

const operations: MyApi.OperationHandlers<MyParams> = {
  greet(req, res, params) {
    // params.context.foo is of type string;
    // req.params.name is of type string
    return {
      message: `Hello ${req.params.name}`
    };
  },
  addPerson(req, res, params) {
    const {person} = req.body;

    // Store the new person
    res.statusCode = 201;
    return person;
  },
  deletePerson(req, res, params) {
    const {name} = req.params;
    // Delete the person
  },
  getTypes(req, res, params) {
    // req.params.foo;
    // req.query.bar
    // req.headers.baz;
    res.headers.something = 'hello';
    return {foo: 'bar'};
  }
}