@kattebak/typespec-openapi-types-emitter

A TypeSpec emitter that generates TypeScript type definitions from your API specifications. Define your API once in TypeSpec and get fully typed client interfaces with complete code completion support.

Features

• Generates TypeScript types directly from TypeSpec API definitions
• Outputs Components.Schemas namespace with all models, enums, and scalars
• Generates Paths namespace with operation-specific types (parameters, request bodies, responses)
• Creates OperationMethods interface for typed API method calls
• Produces PathsDictionary for path-based method access
• Exports convenient top-level type aliases

Installation

npm install @kattebak/typespec-openapi-types-emitter

Usage

1. Add the emitter to your TypeSpec project

Create or update your tspconfig.yaml:

emit:
  - "@kattebak/typespec-openapi-types-emitter"
options:
  "@kattebak/typespec-openapi-types-emitter":
    output-file: "types.d.ts"
    # Optional: generate a package.json for the types
    package-name: "@myorg/api-types"
    package-version: "1.0.0"

2. Compile your TypeSpec project

npx tsp compile .

This will generate a types.d.ts file in your output directory.

Configuration Options

| Option | Type | Default | Description | | -------------------- | ------ | ---------------- | -------------------------------------------------------------- | | output-file | string | "types.d.ts" | The output filename for the generated types | | emitter-output-dir | string | "{output-dir}" | The directory where the types file will be written | | package-name | string | - | If provided, a package.json will be generated with this name | | package-version | string | "0.0.1" | Version for the generated package.json |

Generated Output Structure

The emitter produces TypeScript declarations with the following structure:

declare namespace Components {
  namespace Schemas {
    // All models, enums, and scalar types
    export interface Book { ... }
    export type BookStatus = "available" | "out_of_stock";
    // ...
  }
}

declare namespace Paths {
  namespace GetBooks {
    export interface QueryParameters { ... }
    namespace Responses {
      export type $200 = Components.Schemas.Book[];
    }
  }
  // ... other operations
}

export interface OperationMethods {
  getBooks(
    parameters?: Paths.GetBooks.QueryParameters | null,
    data?: any,
    config?: RequestConfig
  ): Promise<Paths.GetBooks.Responses.$200>;
  // ... other operations
}

export interface PathsDictionary {
  ['/books']: {
    get(...): Promise<...>;
    post(...): Promise<...>;
  };
  // ... other paths
}

// Convenient top-level exports
export type Book = Components.Schemas.Book;
export type BookStatus = Components.Schemas.BookStatus;
// ...

Using the Generated Types

import type { Book, Author, OperationMethods } from "@myorg/api-types";

// Use the types with your API client
const books: Book[] = await client.getBooks({ limit: 10 });
const author: Author = await client.getAuthorById({ id: 1 });

Example

See the test/main.tsp file for a complete example of a Bookstore API definition.

Development

# Install dependencies
npm install

# Build the emitter
npm run build

# Run tests
npm test

# Lint and format
npm run lint
npm run fix

License

MIT