@walecloud/fastify-openapi-typescript-generator

A powerful, type-safe utility for generating TypeScript types and route handler interfaces from OpenAPI definitions for the Fastify framework.

This package takes your OpenAPI 3.x specification (YAML or JSON) and automatically generates strongly-typed route handlers and schema configurations. It pairs exceptionally well with fastify-openapi-glue to automatically map your API specification to your Fastify route handlers.

---

⚠️ Breaking Changes in v1.5.0

If you are upgrading from v1.4.x or earlier, please be aware that the underlying openapi-typescript generator was bumped from v6/v7.8 to v7.13+. This introduces structural changes to how TypeScript generic ASTs are generated and validated from your OpenAPI definition.

Migration Steps:

1. Regenerate Files: After updating to v1.5.0, you must rerun the CLI tools to seamlessly regenerate your types.ts, handlers.ts, and route config schemas. Old schemas natively conflict with the upgraded Fastify AST structures.
2. Verify Type Imports: The new parsing might slightly change how arrays, enums, or deeply nested $refs are output. Confirm inside your typed code blocks that your request.body generics map perfectly to the new shapes.
3. Node.js >= 18.19.x is highly recommended moving forward.

---

🌟 Features

• TypeScript Type Generation: Automatically convert OpenAPI schemas into TypeScript models.
• Strict Route Handlers: Generates Fastify RouteHandlerMethod interfaces specific to each endpoint, ensuring Body, Querystring, Params, Headers, and Reply types match your OpenAPI spec.
• Route Configs Generation: Automatically splits your OpenAPI routes into Fastify-compatible route configuration objects.
• Zero-Boilerplate: Bridges the gap between your API documentation and the actual implementation.

---

📦 Installation

npm install -D @walecloud/fastify-openapi-typescript-generator

(Note: It is recommended to install this as a devDependency since it's a code generation tool).

---

🛠️ Usage

This package exposes two Command Line Interface (CLI) tools to be run locally or within your CI/CD pipelines.

1. Generating TypeScript Types & Handlers

Use fastify-openapi-typescript to read an OpenAPI spec and output strongly typed request/response models and a Handlers interface.

npx fastify-openapi-typescript --input ./openapi.yaml --output ./src/generated

Options:

• -i, --input <path>: (Required) Path to your OpenAPI specification. Supports .yaml, .yml, and .json.
• -o, --output <path>: (Required) Directory where the generated TypeScript files will be saved.
• -h, --help: Display help for the command.
• -V, --version: Output the current version.

What gets generated?

1. types.ts: Full TypeScript interfaces representing your OpenAPI schemas.
2. handlers.ts: An interface Handlers that contains all the operationIds from your OpenAPI spec mapped to strongly-typed Fastify RouteHandlerMethods. Implementing this interface ensures your endpoints are fully type-safe.

2. Generating Route Configurations

Use fastify-openapi-route-configs to extract route options (like Fastify schemas, methods, urls, and configurations) for use with plugins like fastify-openapi-glue.

npx fastify-openapi-route-configs --input ./openapi.yaml --output ./src/routes

Options:

• -i, --input <path>: (Required) Path to your OpenAPI specification.
• -o, --output <path>: (Required) Directory where the configuration files will be generated.
• -h, --help: Display help for the command.

What gets generated? This generates an index.ts file, a types.ts type definition, and a configs/ folder that breaks out each route configuration into its own file. It handles populating the Fastify schema: {} blocks to automatically validate payloads based on your spec.

---

💡 Example Workflow

1. You write an openapi.yaml file defining a POST /users endpoint with an operationId: createUser.
2. You run the fastify-openapi-typescript CLI tool against it.
3. You import the generated Handlers interface into your Fastify controller logic:

import { Handlers } from './generated/handlers'

class UserHandlers implements Handlers {
  // `createUser` is perfectly typed! 
  // Fastify knows exactly what request.body and the expected reply shape should be.
  createUser: Handlers['createUser'] = async (request, reply) => {
    const { name, email } = request.body; // Types automatically inferred
    
    // ... create user logic ...
    
    return reply.status(201).send({ id: 1, name, email }); // Payload matches OpenAPI Response schema
  }
}

---

🤝 Acknowledgments

This is a community-maintained fork of quinck-io/fastify-openapi-typescript-generator, featuring dependency upgrades, comprehensive testing, and extended capabilities.