Support typed request/response schemas for OpenAPI generation

[tom-groves]

Problem

Nitric generates OpenAPI specs during build (as shown in the architecture docs), but the generated specs only include route definitions — no request/response body schemas. This limits the usefulness of the generated spec for:

1. API documentation — Consumers can't see what payloads are expected
2. Client generation — Tools like openapi-typescript produce unknown types for bodies
3. Contract testing — No machine-readable contract to validate against

Currently, developers must validate request bodies manually in handlers, but this knowledge doesn't flow back into the OpenAPI spec.

Suggested Solution

Allow defining schemas using plain TypeScript types:

import { api } from '@nitric/sdk';

interface CreateUserBody {
  name: string;
  email: string;
  age?: number;
}

interface CreateUserResponse {
  id: string;
  name: string;
  email: string;
}

api.post<CreateUserBody, CreateUserResponse>('/users', async (ctx) => {
  const body = ctx.req.json(); // typed as CreateUserBody
  // ...
  return { id: '123', name: body.name, email: body.email };
});

[jyecusch]

Hey @tom-groves thanks for creating this issue. It's something the team have discussed and wanted to do for quite a while. We've always held back because we support multiple langauges and there isn't a clear way to add this universally without a high maintenance burden.

[tom-groves]

Thanks @jyecusch, that makes sense, I just had my TypeScript hat on :-)