Skip to content
Docs

OpenAPI Spec generation key tools question

For OpenAPI spec generation, here are the key tools that can help with your TypeScript/Go stack:

Backend (Go) Generation

  • oapi-codegen - Most popular Go OpenAPI generator, creates server stubs, client code, and types
  • go-swagger - Comprehensive toolkit for Go, generates servers, clients, and models
  • deepmap/oapi-codegen - Lightweight alternative with good performance

Frontend (TypeScript) Generation

  • openapi-typescript - Generates TypeScript types from OpenAPI specs
  • swagger-codegen - Can generate TypeScript clients
  • orval - Modern TypeScript generator with React Query/SWR integration

Fast Validation Libraries

  • Go: go-playground/validator (struct validation) or oapi-codegen built-in validation
  • TypeScript: zod, yup, or ajv for runtime validation

Integration with ts-rest/tRPC

For ts-rest: You can generate TypeScript types from OpenAPI and use them with ts-rest contracts. The workflow would be:

  1. Generate types with openapi-typescript
  2. Create ts-rest contracts using those types
  3. Share the contract between frontend and a TypeScript backend

For tRPC: Since tRPC is TypeScript-first and doesn’t use OpenAPI directly, you’d need to:

  1. Generate TypeScript types from OpenAPI
  2. Create tRPC procedures that conform to those types
  3. This creates some duplication but maintains type safety
  1. Design OpenAPI spec
  2. Generate Go backend with oapi-codegen
  3. Generate TypeScript types with openapi-typescript
  4. Use generated types in your React app with your preferred data fetching library
  5. Add runtime validation with zod on the frontend

This approach gives you the design-first benefits of OpenAPI while maintaining the type safety and performance you want. Yes, there are some generators and integrations that work with Effect and TypeBox:

Effect Integrations

@effect/platform includes HTTP client utilities that can work with generated types:

  • You can use openapi-typescript to generate types, then use them with Effect’s HTTP client
  • effect-http - A library for building HTTP APIs with Effect that includes OpenAPI schema generation
  • @effect/schema - Effect’s own schema library that can be used for validation and type generation

TypeBox Integrations

TypeBox has better OpenAPI tooling support:

  • @sinclair/typebox - The core library has built-in OpenAPI schema generation
  • fastify-type-provider-typebox - If you were using Node.js/Fastify instead of Go
  • typebox-codegen - Generates TypeBox schemas from OpenAPI specs
  • openapi-typebox - Converts OpenAPI specs to TypeBox schemas

Custom Generation Approach

Since you’re using Go backend + TypeScript frontend, you could:

  1. For TypeBox: Use typebox-codegen or openapi-typebox to generate TypeBox schemas from your OpenAPI spec
  2. For Effect: Generate standard TypeScript types with openapi-typescript, then create Effect Schema definitions that use those types

Effect-first Alternative

If you want to go fully Effect-first:

  • Use @effect/schema to define schemas in TypeScript
  • Generate OpenAPI specs from Effect schemas
  • Use the OpenAPI spec to generate your Go backend with oapi-codegen
  • This reverses the typical flow but gives you Effect-native schemas

TypeBox-first Alternative

  • Define schemas with TypeBox
  • Generate OpenAPI specs from TypeBox schemas
  • Use for both frontend validation and Go backend generation

The Effect ecosystem is still evolving for OpenAPI generation, but TypeBox has more mature OpenAPI tooling. Would you prefer to start with OpenAPI-first or schema-first approach?