Gateway Generator
Gateway Generator creates a Fastify API Gateway from an OpenAPI contract.
It reads an OpenAPI YAML or JSON file, extracts the available routes, and generates a ready-to-run Fastify project with route handlers, schemas, optional authentication support, and proxy-oriented structure.
Features
- Generates a Fastify project from OpenAPI contracts.
- Supports YAML and JSON OpenAPI files.
- Groups generated routes by tags.
- Creates route schemas from contract metadata.
- Adds authentication scaffolding when security metadata is present.
- Supports custom gateway metadata such as proxy timeouts and rate limits.
- Can be used from the terminal or through the VS Code extension.
Requirements
- Node.js 20 or newer.
- pnpm, npm, or another Node.js package manager.
- An OpenAPI contract in
.yaml, .yml, or .json format.
Usage with npx
Run Gateway Generator without installing it globally:
npx gateway-generator --input ./openapi.yaml --output ./generated-gateway
You can also use the shorter command alias:
npx gateway-gen --input ./openapi.yaml --output ./generated-gateway
Global Installation
Install the package globally:
npm install -g gateway-generator
Then run:
gateway-generator --input ./openapi.yaml --output ./generated-gateway
or:
gateway-gen --input ./openapi.yaml --output ./generated-gateway
CLI Options
| Option |
Description |
-i, --input <path> |
Path to the OpenAPI contract file. |
-o, --output <dir> |
Directory where the Fastify gateway project will be generated. |
Gateway Generator uses standard OpenAPI fields plus a few custom extensions to decide how each gateway route should be generated.
Required OpenAPI Fields
At minimum, the contract must be a valid OpenAPI document with route operations under paths:
openapi: 3.0.0
info:
title: Example API
version: 1.0.0
paths:
/users:
get:
summary: List users
x-upstream-url: https://api.example.com/users
responses:
"200":
description: OK
Each operation under paths becomes a Fastify route. Supported HTTP methods are get, post, put, delete, patch, options, and head.
Standard OpenAPI Fields Used
| Field |
Where |
How it is used |
paths |
Root document |
Defines the routes that will be generated. |
| HTTP operations |
Inside each path |
Defines the route method, such as get, post, or delete. |
tags |
Operation |
Groups generated route files. If missing, the first path segment is used as a fallback group. |
summary |
Operation |
Adds a human-readable description to the extracted route metadata. |
requestBody.content.application/json.schema |
Operation |
Generates request body validation schemas. |
security |
Operation |
Marks the route as protected and enables JWT authentication in the generated gateway. |
components.schemas |
Root document |
Provides reusable schemas referenced by the contract. |
Custom Extensions
Gateway Generator also reads custom OpenAPI extensions. Add them directly to each operation that should be proxied or configured by the gateway.
| Extension |
Type |
Required |
Description |
x-upstream-url |
string |
Recommended |
Target URL that the generated gateway route should proxy to. Operations without this field are parsed but are not included in the generated proxy route set. |
x-proxy-timeout |
number |
No |
Timeout, in milliseconds, for the upstream request. |
x-rate-limit |
number |
No |
Maximum request limit for the generated route. Values are normalized to a positive integer. |
x-required-roles |
string or string[] |
No |
Role or list of roles required to access the route. When present, the generated route validates the JWT and checks request.user.roles. |
JWT Security
Gateway Generator creates JWT-based authentication scaffolding when an operation includes security or x-required-roles.
If an operation has security, the generated route calls request.server.authenticate(...), which verifies the JWT with @fastify/jwt.
If an operation has x-required-roles, the generated route calls request.server.authorize(...), which verifies the JWT and checks whether request.user.roles contains at least one of the required roles.
The generated authentication plugin reads the JWT secret from JWT_SECRET. For JWT validation to work, the gateway must use the same secret key used by the service that signs the tokens. If the environment variable is not set, the generated gateway uses a development fallback secret that should be changed before production use.
Example operation with gateway-specific metadata:
paths:
/budgets:
post:
tags:
- Budgets
summary: Create budget
security:
- bearerAuth: []
x-upstream-url: https://api.example.com/budgets
x-proxy-timeout: 5000
x-rate-limit: 100
x-required-roles:
- admin
- manager
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateBudgetRequest"
responses:
"201":
description: Created
components:
schemas:
CreateBudgetRequest:
type: object
required:
- name
properties:
name:
type: string
Running the Generated Gateway
After generation, open the output directory and install its dependencies:
cd generated-gateway
pnpm install
pnpm dev
The generated project includes its own package.json, source files, route modules, schemas, and server entry point.
VS Code Extension
Gateway Generator can also be used as a VS Code extension.
After installing the extension, open the Command Palette and run:
Gateway Generator: Criar API Gateway
The extension lets you select the OpenAPI contract file and the output folder through the VS Code interface. Before generating the project, it shows a summary with the number of routes, tags, timeouts, and rate limits found in the contract.
Development
Install dependencies:
pnpm install
Build the project:
pnpm build
Run the CLI locally:
pnpm start -- --input ./openapi.yaml --output ./generated-gateway
Package the VS Code extension:
pnpm package:vsix
License
MIT
