Skill openapi-codegen

OpenAPI Code Generation Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: openapi-codegen for comprehensive documentation.

openapi-typescript (Types Only)

Generates TypeScript types from OpenAPI schemas. Lightweight, no runtime.

# Installation
npm install -D openapi-typescript

# Generate types
npx openapi-typescript ./openapi.yaml -o ./src/types/api.ts
npx openapi-typescript https://api.example.com/openapi.json -o ./src/types/api.ts

Generated Types Usage

import type { paths, components } from './types/api';

// Schema types
type User = components['schemas']['User'];
type CreateUserDto = components['schemas']['CreateUserDto'];

// Request/Response types
type CreateUserRequest = paths['/users']['post']['requestBody']['content']['application/json'];
type UserResponse = paths['/users/{id}']['get']['responses']['200']['content']['application/json'];
type UsersListResponse = paths['/users']['get']['responses']['200']['content']['application/json'];

// Path parameters
type UserPathParams = paths['/users/{id}']['get']['parameters']['path'];

With openapi-fetch

import createClient from 'openapi-fetch';
import type { paths } from './types/api';

const client = createClient<paths>({
  baseUrl: 'https://api.example.com',
});

// Fully typed requests
const { data, error } = await client.GET('/users/{id}', {
  params: { path: { id: '123' } },
});

const { data } = await client.POST('/users', {
  body: { name: 'John', email: 'john@example.com' },
});

// Query parameters
const { data } = await client.GET('/users', {
  params: { query: { status: 'active', page: 1 } },
});

---

openapi-generator-cli (Full Client)

Generates complete API clients with fetch/axios implementations.

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

# Generate TypeScript Fetch client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./src/api-client

# Generate TypeScript Axios client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./src/api-client

Configuration File

# openapitools.json
{
  "$schema": "https://raw.githubusercontent.com/OpenAPITools/openapi-generator-cli/master/apps/generator-cli/src/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "7.0.0",
    "generators": {
      "typescript-client": {
        "generatorName": "typescript-fetch",
        "output": "#{cwd}/src/api-client",
        "inputSpec": "#{cwd}/openapi.yaml",
        "additionalProperties": {
          "supportsES6": true,
          "npmName": "@myorg/api-client",
          "typescriptThreePlus": true,
          "withInterfaces": true
        }
      }
    }
  }
}

Generated Client Usage

import { Configuration, UsersApi } from './api-client';

const config = new Configuration({
  basePath: 'https://api.example.com',
  accessToken: () => localStorage.getItem('token') || '',
});

const usersApi = new UsersApi(config);

// Typed API calls
const users = await usersApi.listUsers({ status: 'active' });
const user = await usersApi.getUserById({ id: '123' });
const newUser = await usersApi.createUser({
  createUserDto: { name: 'John', email: 'john@example.com' },
});

---

swagger-typescript-api

Fast, customizable generator with template support.

# Installation
npm install -D swagger-typescript-api

# Generate
npx swagger-typescript-api -p ./openapi.yaml -o ./src/api -n api.ts

Configuration

npx swagger-typescript-api \
  -p ./openapi.yaml \
  -o ./src/api \
  -n api.ts \
  --axios \                    # Use axios instead of fetch
  --modular \                  # Separate files per tag
  --route-types \              # Generate route types
  --extract-request-body \     # Extract request body types
  --extract-response-body      # Extract response body types

Generated Client Usage

import { Api } from './api/api';

const api = new Api({
  baseUrl: 'https://api.example.com',
  securityWorker: () => ({
    headers: { Authorization: `Bearer ${getToken()}` },
  }),
});

// Typed API calls
const users = await api.users.usersList({ status: 'active' });
const user = await api.users.usersDetail('123');
const newUser = await api.users.usersCreate({
  name: 'John',
  email: 'john@example.com',
});

---

trpc-openapi (Export tRPC as OpenAPI)

Generate OpenAPI spec from tRPC router. Useful for external API consumers.

npm install trpc-openapi

Define OpenAPI Endpoints

import { initTRPC } from '@trpc/server';
import { OpenApiMeta } from 'trpc-openapi';
import { z } from 'zod';

const t = initTRPC.meta<OpenApiMeta>().create();

export const appRouter = t.router({
  getUser: t.procedure
    .meta({
      openapi: {
        method: 'GET',
        path: '/users/{id}',
        tags: ['users'],
        summary: 'Get user by ID',
      },
    })
    .input(z.object({ id: z.string() }))
    .output(z.object({
      id: z.string(),
      name: z.string(),
      email: z.string(),
    }))
    .query(({ input }) => getUserById(input.id)),

  createUser: t.procedure
    .meta({
      openapi: {
        method: 'POST',
        path: '/users',
        tags: ['users'],
        summary: 'Create a new user',
      },
    })
    .input(z.object({
      name: z.string(),
      email: z.string().email(),
    }))
    .output(z.object({
      id: z.string(),
      name: z.string(),
      email: z.string(),
    }))
    .mutation(({ input }) => createUser(input)),
});

Generate OpenAPI Document

import { generateOpenApiDocument } from 'trpc-openapi';
import { appRouter } from './router';

const openApiDocument = generateOpenApiDocument(appRouter, {
  title: 'My API',
  version: '1.0.0',
  baseUrl: 'https://api.example.com',
});

// Save to file
import fs from 'fs';
fs.writeFileSync('./openapi.json', JSON.stringify(openApiDocument, null, 2));

REST Handler

import { createOpenApiNextHandler } from 'trpc-openapi';
import { appRouter } from './router';

// Next.js API route: pages/api/[...trpc].ts
export default createOpenApiNextHandler({
  router: appRouter,
  createContext: () => ({}),
});

---

Production Readiness

CI/CD Integration

# .github/workflows/generate-client.yml
name: Generate API Client

on:
  push:
    paths:
      - 'openapi.yaml'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Generate types
        run: npx openapi-typescript ./openapi.yaml -o ./src/types/api.ts

      - name: Check for changes
        id: check
        run: |
          if git diff --quiet src/types/api.ts; then
            echo "changed=false" >> $GITHUB_OUTPUT
          else
            echo "changed=true" >> $GITHUB_OUTPUT
          fi

      - name: Commit and push
        if: steps.check.outputs.changed == 'true'
        run: |
          git config --local user.email "bot@example.com"
          git config --local user.name "API Generator Bot"
          git add src/types/api.ts
          git commit -m "chore: regenerate API types"
          git push

Package Scripts

{
  "scripts": {
    "generate:types": "openapi-typescript ./openapi.yaml -o ./src/types/api.ts",
    "generate:client": "openapi-generator-cli generate -c openapitools.json",
    "generate:all": "npm run generate:types && npm run generate:client",
    "precommit": "npm run generate:types && git add src/types/api.ts"
  }
}

Watch Mode Development

# openapi-typescript with watch
npx openapi-typescript ./openapi.yaml -o ./src/types/api.ts --watch

# Or use nodemon
npx nodemon --watch openapi.yaml --exec "npx openapi-typescript ./openapi.yaml -o ./src/types/api.ts"

Validation Before Generation

# Validate spec first
npx @redocly/cli lint openapi.yaml

# Then generate
npx openapi-typescript ./openapi.yaml -o ./src/types/api.ts

Monitoring Metrics

Metric	Target
Generated type coverage	100% of endpoints
Build time with generation	< 30s
Type errors after generation	0
Spec validation errors	0

Checklist

• OpenAPI spec validation in CI
• Automated type generation on spec changes
• Generated code committed or gitignored
• Version pinned for generator CLI
• Custom templates documented
• API client initialization documented
• Error handling patterns documented
• Authentication setup in client
• Breaking change detection
• Generated code tested

When NOT to Use This Skill

• Writing OpenAPI specifications (use openapi skill)
• GraphQL type generation (use graphql-codegen skill)
• tRPC type-safe APIs (use trpc skill)
• Manual API client implementation
• Simple APIs where manual types suffice

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Committing generated code to git	Merge conflicts, stale code	Add to .gitignore, generate in CI/build
Not versioning generator CLI	Inconsistent output	Pin generator versions in package.json
Editing generated files manually	Changes lost on regeneration	Extend or wrap generated code
No validation before generation	Invalid types generated	Validate spec with @redocly/cli first
Using different generators across team	Type inconsistencies	Standardize on one generator
Generating from remote spec without caching	Slow builds, network dependency	Cache spec locally or use schema registry
Not updating on spec changes	Type/runtime mismatch	Run generation in CI on spec updates
Missing error handling in generated code	Poor error UX	Wrap generated client with error handling

Quick Troubleshooting

Issue	Possible Cause	Solution
Generation fails	Invalid OpenAPI spec	Validate with @redocly/cli lint
Type errors after generation	Spec doesn't match API	Verify spec matches actual responses
Missing types	Spec incomplete or refs broken	Check all $refs resolve, add missing schemas
Wrong HTTP client generated	Generator config mismatch	Check -g flag or generator setting
Circular reference errors	Self-referencing schemas	Use discriminators or flatten schema
Slow generation	Large spec file	Use spec splitting or partial generation
Auth not working	Security scheme not configured	Add securityWorker or token config
"Cannot find module" errors	Generation didn't complete	Check for generation errors, rerun
Type conflicts	Multiple generators running	Use single generator, remove others

Reference Documentation

• openapi-typescript
• openapi-generator
• swagger-typescript-api
• trpc-openapi