mcpField
O
openapi-ts-v0

openapi-ts-v0

github.com/blockmaticDevelopment1221 installsUpdated 5w ago
Repository

About openapi-ts-v0

A skill guide for TypeScript developers generating clients from OpenAPI 3.0 specifications with @hey-api/openapi-ts. It covers configuration, typed responses and errors, and integration patterns with tools such as TanStack Query.

Key features

  1. 01Generate TypeScript clients from OpenAPI specs
  2. 02Create typed client methods from specifications
  3. 03Configure output format and schema types
  4. 04Handle typed error responses
  5. 05Review TanStack Query integration

Use cases

  1. 01Generate a TypeScript client for an OpenAPI API
  2. 02Call typed API methods from application code
  3. 03Write TanStack Query hooks using a generated client

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/blockmatic/basilic-skills --skill openapi-ts-v0

After installing, type/openapi-ts-v0in Claude Code to confirm it loaded.

Bundled filesreferences/react-query-integration.mdtemplates/openapi-ts.config.ts

Details

From the project README

Skill: openapi-ts

Scope

  • Applies to: Generating TypeScript clients from OpenAPI 3.0 specifications using @hey-api/openapi-ts
  • Does NOT cover: Writing OpenAPI specs, API server implementation (see fastify)

Assumptions

  • @hey-api/openapi-ts v0+
  • OpenAPI 3.0 specification format
  • TypeScript v5+ with strict mode
  • Default output is types and client only; React Query hooks are handwritten in consuming apps

Principles

  • Generate clients from OpenAPI specs (single source of truth)
  • Client methods are fully typed from OpenAPI spec
  • Error responses are typed from OpenAPI error schemas
  • Use createClient factory for client instantiation
  • Configure output format and schema type in config file
  • Zod schemas and generated React Query plugins are optional add-ons

Constraints

MUST
  • Use openapi-ts.config.ts for configuration
  • Generate clients before using in code
  • Handle response.error for typed error responses
SHOULD
  • Use Prettier formatting (output.format: 'prettier')
  • Generate TypeScript enums (types.enums: 'typescript')
  • Write TanStack Query hooks by hand against the generated client
  • Add Zod schemas (schemas.type: 'zod') only when runtime validation is required
  • Add generated React Query plugin only when the project opts into it
AVOID
  • Manually editing generated code
  • Using generated clients without error handling
  • Mixing generated and manual client code

Interactions

Patterns

Configuration Pattern
// openapi-ts.config.ts
import { defineConfig } from '@hey-api/openapi-ts'

export default defineConfig({
  input: './openapi.json',
  output: {
    path: './src/gen',
    format: 'prettier',
  },
  types: {
    enums: 'typescript',
  },
})
Client Usage Pattern
import { createClient } from './gen/client'

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

const response = await client.GET('/users/{id}', {
  params: { path: { id: '123' } },
})

if (response.error) {
  // Handle typed error
  return
}

// response.data is typed from OpenAPI spec

See Config Template for complete example.

References

Comments

Markdown supported