Teams almost always fall into the same confusion around OpenAPI at first: frontend developers treat the endpoint list page purely as a web reference for human eyes. Given a link to the docs, a developer opens a browser tab, expands colored request panels, squints at response fields, and manually retypes interface User or payment parameters into the code editor. The visual wrapper gets mistaken for the tool itself, even though the web page is just a storefront over a machine-readable contract file.
As long as that contract is copied into the project by hand, the frontend stays hostage to someone else's schedule: if the backend hasn't deployed a staging environment yet, layout and logic grind to a halt, and any field rename on the server surfaces only when staging breaks. In a breakdown on Node.JS ru and a detailed article on Хабр, an engineer going by itwillwork laid out step by step how to turn a raw OpenAPI schema into a working frontend pipeline. What stood out to me most in this guide is how pairing a type generator, a local mock server, and schema patching completely decouples the frontend from backend readiness.
A Contract Instead of a Reference: Pulling the Raw Schema from Web Docs
The OpenAPI specification (formerly Swagger) is a YAML or JSON document that strictly describes REST API routes, call parameters, and data structures. If we compare development to a restaurant, the web docs UI is the glossy menu for guests, while the OpenAPI file itself is the kitchen's spec sheet that automatically configures the register, pantry, and order form.
The logic here is straightforward: if your browser renders an interactive method table in Swagger UI or ReDoc, it just downloaded the source schema file over the network. You don't need to ping a backend engineer in DMs for the file—just open the Network tab in DevTools, reload the page, and find the request for a .json, .yaml, or .yml file whose first line specifies the standard version (openapi: 3.0.x or 3.1.x).
Let's see how this changes things in practice. Suppose your team picks up an integration for a new payment gateway and payer profile this sprint, but the backend only has an early draft ./schema/openapi.yaml and staging won't be ready for another week. By pulling that file into the repository, you spin up strict response types and a local stub server in 5 minutes, building the UI smoothly from day one of the sprint.
Clean Types with Zero Bundle Bloat: How openapi-typescript Works
The first link in this pipeline is extracting TypeScript interfaces directly from the schema automatically. On a modern stack (Node.js 18+ and TypeScript 5+), writing DTO models by hand makes no sense: the faster an API evolves early in a product, the higher the chance of missing a changed field during manual checks.
For a long time, developers were put off by heavy legacy toolchains like @openapitools/openapi-generator-cli, which generate SDKs for 50+ languages but drag bulky classes and extra runtime code into a project. In my view, openapi-typescript handles the job far more cleanly. It works like a pure schema compiler: it reads a local file or URL for an OpenAPI 3.0/3.1 spec and translates paths, operations, and components into a flat .d.ts declaration file with zero bytes added to the final JavaScript bundle. Just add npx openapi-typescript ./schema/openapi.yaml -o ./src/types/api.d.ts to package.json, and any field change on the server is flagged immediately by tsc before you commit.
Wiring Types to Requests and a Local Mock Server in Five Minutes
To put .d.ts declarations to full use, the generated structures are wired to a network client and pointed at a local mock server while the real payment gateway backend is still being written:
- For native
fetch, the lightweight openapi-fetch client (~6 KB) pairs with the generator, taking thepathsinterface and inferring route, parameter, and response types. - For TanStack React Query, Orval generates ready-made query hooks, while @rtk-query/codegen-openapi does the same for Redux Toolkit.
- In a Node.js and Express BFF layer, shared types plug into controllers while express-openapi-validator validates requests and responses against the schema at runtime.
Let's assemble a working loop for our scenario: install the generator packages and the Stoplight Prism CLI mock server, generate types from ./schema/openapi.yaml, launch the API emulator on port 4010, and make a typed user-profile request:
// In the terminal:
// npm install -D openapi-typescript @stoplight/prism-cli && npm install openapi-fetch
// npx openapi-typescript ./schema/openapi.yaml -o ./src/types/api.d.ts
// npx prism mock ./schema/openapi.yaml -p 4010
import createClient from 'openapi-fetch';
import type { paths } from './types/api';
const client = createClient<paths>({ baseUrl: 'http://localhost:4010' });
// Full autocomplete for endpoints, parameters, and response body:
const { data, error } = await client.GET('/v1/users/{userId}', {
params: { path: { userId: '123' } },
});
By passing the paths interface to createClient<paths>(), we tightly bind the '/v1/users/{userId}' URL template to the required params.path.userId property. If you mistype the URL or forget the ID, the build fails at type-checking, while your editor immediately autocompletes fields on data and error.
On port 4010, the request hits the local prism mock process. It reads ./schema/openapi.yaml, validates call headers and parameters, and returns a JSON response from the schema's examples. Keep one boundary in mind: Prism returns static or randomized data with no state persistence across calls. So for multi-step flows where a payment updates a balance on the next request, teams layer a Service Worker via msw-auto-mock or generate fixtures with openapi-sampler and json-schema-faker.
When the Contract Lies: Declarative Schema Patching with openapi-modifier
In practice, almost every team hits the same snag: the backend's spec is rarely spotless. When writing YAML by hand, server developers make typos—writing type: int instead of type: integer, format: datetime instead of date-time, or forgetting type: object on a model. And when schemas are auto-generated from code, internal /internal/ and /private/ routes or constructs that break the generator slip in.
The first impulse is to open the downloaded openapi.yaml or api.d.ts and fix the error by hand. Yet that patch survives only until the next file pull from the server, when all manual edits are wiped out (I showed why you shouldn't edit generated contracts by hand in our breakdown of auto-generating TypeScript types from OpenAPI in a Laravel and TypeScript stack). Standard schema linters won't save you here either: they only report the error in the console without fixing someone else's file.
To avoid waiting on backend fixes, itwillwork puts a declarative transformation pipeline ahead of codegen using openapi-modifier. In openapi-modifier.config.js, you define a chain of rules (pipeline) that, when running npx openapi-modifier, takes ./schema/openapi.yaml and writes a patched copy to ./schema/openapi.prepared.yaml:
- Targeted type fixes (
patch-component-schema): a rule withpatchMethod: 'merge'locates a descriptor likeUser.idorPet.idand replaces the broken definition with{ type: 'string', format: 'uuid' }(or fixesinttointeger) while preserving the rest of the model's fields. - Adding features before backend release (
merge-openapi-specanddeepmerge): if taskJIRA-232needs a screen built before the endpoint exists in the shared schema,merge-openapi-specmerges in a draftdocs/feature-JIRA-232.yaml, andpatchMethod: 'deepmerge'adds the new property to the model. - Cleanup and deprecation checks: a
filter-endpointsrule matching/^\/internal\//strips internal endpoints,remove-unused-componentsdrops orphaned schemas, andremove-deprecatedandremove-parameterremove deprecated parameters so TypeScript itself flags calls that need rewriting.
Chain contract preparation and type generation into a single package.json script: first npx openapi-modifier runs rules annotated with ticket numbers (such as JIRA-8752) to produce openapi.prepared.yaml, and then npx openapi-typescript builds api.d.ts from it. Once the backend fixes the typo on its side, the temporary rule is deleted from the config in one line.
Ultimately, combining the raw schema, the Prism mock server, declarative patching via openapi-modifier, and openapi-typescript removes sprint blockers: the frontend builds a working payment gateway UI before staging is ready. And if you want to see examples for RTK Query, React Query, and Express or grab the full transformation-rule cheat sheet, check out the original article on Хабр.

![Node.JS [ru]](/api/digests/it_development/daily/20261112/assets/sources/we-use-js.jpg?v=96d603ea907a603e2476230869b24b042f87006317785f577b52227c3db5cc47)
