Version: 11.x

OpenAPI (alfa)

Inofficiell Beta-översättning

Denna sida har översatts av PageTurner AI (beta). Inte officiellt godkänd av projektet. Hittade du ett fel? Rapportera problem →

försiktighet

Detta paket är i alfastadie. API:er kan ändras utan förvarning.

Paketet @trpc/openapi genererar en OpenAPI 3.1-specifikation från din tRPC-router. Använd specifikationen för att:

Generera en typad API-klient i valfritt språk
Anropa tRPC-endpunkter via HTTP-verktyg som Postman eller Insomnia
Aktivera AI-agentintegrationer som MCP-servrar

Installation

bash
pnpm add @trpc/openapi

bash
pnpm add @trpc/openapi

AI-agenter

Om du använder en AI-kodningsagent, installera tRPC-färdigheter för bättre kodgenerering:

bash
npx @tanstack/intent@latest install

bash
npx @tanstack/intent@latest install

notering

@trpc/openapi har för närvarande versionsnummer som 11.x.x-alfa och bör fungera med alla senare tRPC v11-versioner. Men som alltid rekommenderar vi att versionsnumren matchar.

Anpassa din tRPC-installation

Generatorn fungerar med din befintliga router – inga annoteringar eller dekoratörer krävs. Här är några saker att tänka på:

Inga utdatatyper behövs – till skillnad från andra OpenAPI-verktyg är .output()-scheman valfria. Generatorn härleder returtyper automatiskt från din implementation.
Transformatorer – om din server använder en datatransformator måste dina OpenAPI-klienter använda samma. Se Transformatorer för inställningar och flerspråksalternativ.
Prenumerationer – exkluderas för närvarande från den genererade specifikationen. Stöd för SSE är planerat.
Beskrivningar – Zod .describe()-anrop och JSDoc-kommentarer på typer, routers och procedurer blir alla description-fält i specifikationen.

Generera specifikationen

CLI

bash
pnpm exec trpc-openapi ./src/server/router.ts

bash
pnpm exec trpc-openapi ./src/server/router.ts

Option	Default	Description
`-e, --export <name>`	`AppRouter`	Name of the exported router type
`-o, --output <file>`	`openapi.json`	Output file path
`--title <text>`	`tRPC API`	OpenAPI `info.title`
`--version <ver>`	`0.0.0`	OpenAPI `info.version`

bash
pnpm exec trpc-openapi ./src/server/router.ts -o api.json --title "My API" --version 1.0.0

bash
pnpm exec trpc-openapi ./src/server/router.ts -o api.json --title "My API" --version 1.0.0

Programmatiskt

scripts/generate-openapi.ts
ts
import { generateOpenAPIDocument } from '@trpc/openapi';
const doc = generateOpenAPIDocument('./src/server/router.ts', {
  exportName: 'AppRouter',
  title: 'My API',
  version: '1.0.0',
});

scripts/generate-openapi.ts
ts
import { generateOpenAPIDocument } from '@trpc/openapi';
const doc = generateOpenAPIDocument('./src/server/router.ts', {
  exportName: 'AppRouter',
  title: 'My API',
  version: '1.0.0',
});

Generatorn analyserar din routers TypeScript-typer statiskt – den exekverar aldrig din kod.

Generera en klient från specifikationen

Vilken OpenAPI-klientgenerator som helst bör fungera, men den mest testade integrationen är med Hey API.

En genererad klient skapar typade SDK-funktioner som matchar dina tRPC-procedurer:

Frågor → GET /procedure.path
Mutationer → POST /procedure.path
Prenumerationer ignoreras (SSE kommer snart)

Hey API (TypeScript)

Hey API-dokumentation

bash
pnpm add @trpc/openapi @hey-api/openapi-ts

bash
pnpm add @trpc/openapi @hey-api/openapi-ts

Direkt efter generering vet inte en OpenAPI-klient om din transformatorkonfiguration eller hur frågeparametrar ska kodas. Paketet @trpc/openapi/heyapi tillhandahåller en configureTRPCHeyApiClient-hjälpfunktion som överbryggar detta – den konfigurerar serialisering av förfrågningar, parsning av svar och avserialisering av fel så att det genererade SDK:t fungerar korrekt med tRPC-endpunkter.

Utan transformator

I det här fallet kan du generera din klient med Hey API:s CLI eller programmatiska API

bash
pnpm exec openapi-ts -i openapi.json -o ./generated

bash
pnpm exec openapi-ts -i openapi.json -o ./generated

Sedan krävs lite konfiguration vid körning:

src/usage.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import { client } from './generated/client.gen';
import { Sdk } from './generated/sdk.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
});
const sdk = new Sdk({ client });
const result = await sdk.greeting({ query: { input: { name: 'World' } } });
const user = await sdk.user.create({ body: { name: 'Bob', age: 30 } });

src/usage.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import { client } from './generated/client.gen';
import { Sdk } from './generated/sdk.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
});
const sdk = new Sdk({ client });
const result = await sdk.greeting({ query: { input: { name: 'World' } } });
const user = await sdk.user.create({ body: { name: 'Bob', age: 30 } });

Med transformator (superjson, devalue, etc.)

varning

Om din backend använder en datatransformator som superjson måste du skicka med den till klientkonfigurationen. Utan detta kan datum, kartor, mängder och andra icke-JSON-typer bli felaktiga utan varning.

Generera först din klientkod med Hey API:s programmatiska API. På detta sätt kan du använda createTRPCHeyApiTypeResolvers för att säkerställa att dina genererade typer är korrekta:

src/client.ts
ts
import { createClient } from '@hey-api/openapi-ts';
import { createTRPCHeyApiTypeResolvers } from '@trpc/openapi/heyapi';
const openApiJson = './path/to/openapi.json'
const outputDir = './generated'
await createClient({
  input: openApiJson,
  output: outputDir,
  plugins: [
    {
      name: '@hey-api/typescript',
      // Important: this ensures that your emitted types like Dates are correct
      '~resolvers': createTRPCHeyApiTypeResolvers(),
    },
    {
      name: '@hey-api/sdk',
      operations: { strategy: 'single' },
    },
  ],
});

src/client.ts
ts
import { createClient } from '@hey-api/openapi-ts';
import { createTRPCHeyApiTypeResolvers } from '@trpc/openapi/heyapi';
const openApiJson = './path/to/openapi.json'
const outputDir = './generated'
await createClient({
  input: openApiJson,
  output: outputDir,
  plugins: [
    {
      name: '@hey-api/typescript',
      // Important: this ensures that your emitted types like Dates are correct
      '~resolvers': createTRPCHeyApiTypeResolvers(),
    },
    {
      name: '@hey-api/sdk',
      operations: { strategy: 'single' },
    },
  ],
});

Konfigurera den genererade klienten med din transformator vid körning. Du kan sedan skicka inbyggda typer direkt och få tillbaka dem avserialiserade:

src/usage.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import superjson from 'superjson';
import { client } from './generated/client.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  // Important, this transformer must match your tRPC API's transformer:
  transformer: superjson,
});
const sdk = new Sdk({ client });
const event = await sdk.getEvent({
  query: { input: { id: 'evt_1', at: new Date('2025-06-15T10:00:00Z') } },
});
// event.data.result.data.at is a Date object ✅
const created = await sdk.createEvent({
  body: { name: 'Conference', at: new Date('2025-09-01T09:00:00Z') },
});

src/usage.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import superjson from 'superjson';
import { client } from './generated/client.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  // Important, this transformer must match your tRPC API's transformer:
  transformer: superjson,
});
const sdk = new Sdk({ client });
const event = await sdk.getEvent({
  query: { input: { id: 'evt_1', at: new Date('2025-06-15T10:00:00Z') } },
});
// event.data.result.data.at is a Date object ✅
const created = await sdk.createEvent({
  body: { name: 'Conference', at: new Date('2025-09-01T09:00:00Z') },
});

Använda en annan generator eller språk

Den genererade OpenAPI-specifikationen fungerar med vilken OpenAPI-kompatibel klientgenerator som helst som kan:

Generera korrekta typer för klasser som Date
Stödja anpassning av sökparametrar samt serialisering av förfrågans- och svarskroppar

För att korrekt integrera med tRPC:s protokoll måste du konfigurera din genererade klient att göra två saker:

Transformatorer — Om din tRPC-API använder en transformator måste klienten serialisera indata och deserialisera utdata med samma format
Frågeindata — GET-förfrågningar kodar indata som ?input=<JSON>, inte som enskilda frågeparametrar

Se Hey API-konfigurationskällan för en komplett referensimplementation.

Transformatorer

tRPC:s datatransformatorer låter dig skicka rika typer som Date, Map, Set och BigInt över nätet. När du använder OpenAPI-klienten måste samma transformator konfigureras på både server och klient så att indata serialiseras och utdata deserialiseras korrekt.

Vilken transformator som helst som implementerar tRPC:s DataTransformer-gränssnitt (serialize / deserialize) fungerar med configureTRPCHeyApiClient. Nedan följer några testade alternativ.

SuperJSON

Den mest populära transformatorn för TypeScript-till-TypeScript-inställningar. Hanterar Date, Map, Set, BigInt, RegExp och mer.

bash
pnpm add superjson

bash
pnpm add superjson

src/server.ts
ts
import { initTRPC } from '@trpc/server';
import superjson from 'superjson';
const t = initTRPC.create({ transformer: superjson });

src/server.ts
ts
import { initTRPC } from '@trpc/server';
import superjson from 'superjson';
const t = initTRPC.create({ transformer: superjson });

src/client.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import superjson from 'superjson';
import { client } from './generated/client.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  transformer: superjson,
});

src/client.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import superjson from 'superjson';
import { client } from './generated/client.gen';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  transformer: superjson,
});

Se superjson-testet för ett komplett heltäckande exempel.

MongoDB Extended JSON v2

EJSON är ett bra val när du behöver stöd över flera språk. bson-npm-paketet tillhandahåller EJSON.serialize / EJSON.deserialize som mappar direkt till en tRPC-DataTransformer.

Tillgänglig i: C, C#, C++, Go, Java, Node.js, Perl, PHP, Python, Ruby, Scala

bash
pnpm add bson

bash
pnpm add bson

src/transformer.ts
ts
import { EJSON } from 'bson';
import type { TRPCDataTransformer } from '@trpc/server';
export const ejsonTransformer: TRPCDataTransformer = {
  serialize: (value) => EJSON.serialize(value),
  deserialize: (value) => EJSON.deserialize(value as Document),
};

src/transformer.ts
ts
import { EJSON } from 'bson';
import type { TRPCDataTransformer } from '@trpc/server';
export const ejsonTransformer: TRPCDataTransformer = {
  serialize: (value) => EJSON.serialize(value),
  deserialize: (value) => EJSON.deserialize(value as Document),
};

src/client.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import { client } from './generated/client.gen';
import { ejsonTransformer } from './transformer';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  transformer: ejsonTransformer,
});

src/client.ts
ts
import { configureTRPCHeyApiClient } from '@trpc/openapi/heyapi';
import { client } from './generated/client.gen';
import { ejsonTransformer } from './transformer';
configureTRPCHeyApiClient(client, {
  baseUrl: 'http://localhost:3000',
  transformer: ejsonTransformer,
});

Se MongoDB EJSON-testet för ett komplett heltäckande exempel.

Amazon Ion

Amazon Ion är ett rikt typat dataformat med brett språkstöd. Det stöder inte direkt TRPCDataTransformer-gränssnittet och kräver lite boilerplate för att fungera med tRPC i JS/TS, men kan vara ett bra val för ditt eget system.

Tillgänglig i: C, C#, D, Go, Java, JavaScript, PHP, Python, Rust

bash
pnpm add ion-js

bash
pnpm add ion-js

Se Amazon Ion-testet för transformatorimplementationen, boilerplate och ett komplett heltäckande exempel.

Skriva en anpassad transformator

Vilket objekt som helst med serialize- och deserialize-metoder fungerar:

ts
import type { TRPCDataTransformer } from '@trpc/server';
const myTransformer: TRPCDataTransformer = {
  serialize: (value) => {
    /* encode rich types */
  },
  deserialize: (value) => {
    /* decode them back */
  },
};

ts
import type { TRPCDataTransformer } from '@trpc/server';
const myTransformer: TRPCDataTransformer = {
  serialize: (value) => {
    /* encode rich types */
  },
  deserialize: (value) => {
    /* decode them back */
  },
};

Skicka den till både initTRPC.create({ transformer }) på servern och configureTRPCHeyApiClient(client, { transformer }) på klienten. Se dokumentationen för datatransformatorer för mer detaljer.

Fullständigt exempel

För ett komplett, körbart projekt som binder ihop alla dessa steg, se openapi-codegen-exemplet.

Installation​

Anpassa din tRPC-installation​

Generera specifikationen​

CLI​

Programmatiskt​

Generera en klient från specifikationen​

Hey API (TypeScript)​

Utan transformator​

Med transformator (superjson, devalue, etc.)​

Använda en annan generator eller språk​

Transformatorer​

SuperJSON​

MongoDB Extended JSON v2​

Amazon Ion​

Skriva en anpassad transformator​

Fullständigt exempel​