How do I set up a code scaffolding tool for generating request wrappers from an OpenAPI spec?

A good way to do this is to make the scaffolding tool read your OpenAPI spec and generate a small, consistent client layer around it.

1) Pick a generator

Common options:

• OpenAPI Generator – very flexible, supports many languages
• Swagger Codegen – older, still used
• Orval – great for TypeScript/React query style clients
• Fern – more opinionated, good DX
• NSwag – strong for .NET / C#

If you want “request wrappers” specifically, OpenAPI Generator is usually the most universal choice.

---

2) Define what you want generated

Decide what your wrappers should look like:

• one function per endpoint
• typed request/response bodies
• optional auth headers
• centralized base URL + fetch/axios client
• error handling behavior
• generated models/types too, or only wrappers

Example wrapper shape:

export async function getUser(id: string): Promise<User> {
  return http.get(`/users/${id}`);
}

---

3) Add your OpenAPI spec to the project

Typical layout:

project/
  openapi/
    spec.yaml
  generated/
    api/
    models/
  src/

Keep the spec in version control if it’s maintained in the repo, or point the generator at a remote URL if it’s hosted elsewhere.

---

4) Install the generator

Example: OpenAPI Generator CLI

npm install @openapitools/openapi-generator-cli -D

Or via Docker if you want a clean environment:

docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate ...

---

5) Configure generation

Create a config file, for example openapi-generator.json:

{
  "generatorName": "typescript-fetch",
  "inputSpec": "./openapi/spec.yaml",
  "outputDir": "./generated/api",
  "additionalProperties": {
    "npmName": "my-api-client",
    "supportsES6": true,
    "useSingleRequestParameter": true
  }
}

If you want axios-based wrappers, use a generator/template that supports axios, or customize the templates.

---

6) Run generation

npx openapi-generator-cli generate -c openapi-generator.json

This will generate:

• request functions / API classes
• type definitions
• serialization helpers
• sometimes a shared runtime client

---

7) Wire it into your build

Add scripts to package.json:

{
  "scripts": {
    "generate:api": "openapi-generator-cli generate -c openapi-generator.json",
    "build": "npm run generate:api && tsc"
  }
}

If you don’t want generated files committed, add them to .gitignore. If you do commit them, make sure generation is deterministic.

---

8) Customize the wrappers

You may want to:

• rename endpoints for better function names
• unify auth injection
• add retry logic
• normalize error responses
• use a custom HTTP client

With OpenAPI Generator, this can be done via:

• additional properties
• custom templates
• post-processing scripts

Example custom wrapper layer:

import { UsersApi, Configuration } from "./generated/api";

const config = new Configuration({
  basePath: process.env.API_URL,
  accessToken: () => localStorage.getItem("token") ?? ""
});

export const usersApi = new UsersApi(config);

---

9) Validate the spec before generation

If generation fails often, run spec validation in CI:

• openapi-generator-cli validate
• swagger-cli validate
• spectral lint

This catches malformed schemas, missing refs, invalid paths, etc.

---

10) Add CI checks

A common setup is:

• validate OpenAPI spec
• generate code
• fail if generated output differs from committed files, or regenerate during CI

This keeps wrappers in sync with the spec.

---

Example end-to-end setup

openapi-generator.json

{
  "generatorName": "typescript-fetch",
  "inputSpec": "./openapi/spec.yaml",
  "outputDir": "./src/generated",
  "additionalProperties": {
    "useSingleRequestParameter": true,
    "withSeparateModelsAndApi": true
  }
}

package.json

{
  "scripts": {
    "api:generate": "openapi-generator-cli generate -c openapi-generator.json",
    "api:validate": "openapi-generator-cli validate -i ./openapi/spec.yaml"
  }
}

---

Recommendation

If you’re starting from scratch:

• use OpenAPI Generator
• generate typed request wrappers + models
• keep a thin custom client layer on top
• validate the spec in CI

If you want, I can also give you:

1. a TypeScript + fetch setup,
2. a TypeScript + axios setup,
3. or a Python / Java / C# version.