Coder Legion - Recent posts tagged openapi

Adding OpenAPI Support to Mummy, a Nim HTTP Framework

Sun, 13 Sep 2026 22:28:03 +0000

Adding OpenAPI Support to Mummy: Lessons from Extending Nim's Thread-Per-Request HTTP Server

Mummy is a multi-threaded HTTP 1.1 and WebSocket server for Nim built around a simple, unapologetic idea: skip async/await entirely and let a pool of worker threads handle requests the old-fashioned way — one thread, one request, blocking calls allowed. No Future[T], no colored functions, no async stack traces to untangle. For a systems language with real threads and ARC/ORC to make that cheap, it's a compelling trade.

What Mummy doesn't ship with, though, is any notion of API documentation. There's no built-in way to describe your routes, generate a schema, or hand a frontend team (or your future self) a /docs page. That gap is what got me building.

Why This Gap Matters

Nim's web ecosystem is small enough that most frameworks are optimized for the author's own use case first. Mummy is optimized for raw throughput and simplicity — and it succeeds at both. But once an API has more than a couple of routes, "read the source to find out what a request body looks like" stops scaling. OpenAPI (formerly Swagger) solves this by generating a machine-readable schema of your API directly from your code, which then powers interactive docs, client SDK generation, and request validation.

I forked Mummy and built this in as a layer on top, rather than a separate tool that has to be kept in sync by hand.

What I Built

The fork adds two core modules — openapi_schema.nim and openapi_router.nim — plus an OpenApiRouter that wraps Mummy's normal routing with metadata: summaries, tags, and response schemas generated via schemaOf. Every one of the 12 bundled examples now serves a live /openapi.json and an interactive /docs page, generated from the same route definitions that handle requests — no separate spec file to maintain.

From there I added three more pieces that came up naturally once the schema layer existed:

Typed path params (openapi_params.nim) — pathParam[T](request, "id") pulls a path segment straight out as an int, string, or whatever type you declare, instead of manually parsing strings on every handler.
Request body validation (openapi_validation.nim) — parseValidatedBody[T] checks an incoming JSON body against the same schema that schemaOf generated for your docs, so the validation and the documentation can't drift apart.
Composable middleware (openapi_middleware.nim) — a Middleware type and a use() method on the router, with logging and bearer-auth middleware included out of the box.

Every feature was compiled and exercised with real HTTP requests, not just nim check, before I called it done — including converting a wildcard WebSocket route to a named path param and confirming it fixed a small latent bug where the old code read the raw request URI (query string and all) instead of the decoded path.

What the Wider Nim Community's Experience With Mummy Adds

Reading through discussion around Mummy on the Nim mailing list and forum was useful context while building this. One recurring theme: Mummy's design intentionally keeps some things out of scope in the name of simplicity. A developer comparing thread-per-request servers noted that Mummy's multipart handling, while present, buffers the entire upload into memory rather than streaming it — a deliberate trade-off for simplicity that matters if you're building something like a file-upload service, and pointed to alternatives like Guildenstern for cases needing streaming multipart support.

That trade-off is directly relevant to schema-driven validation work: parseValidatedBody[T] inherits the same "load it all, then check it" model. For typical JSON APIs that's a non-issue, but it's a useful thing to know going in if you're planning a Mummy-based service that also needs large file uploads — you may want to keep that path outside the validated-body flow rather than fight the framework's grain.

It's also worth knowing you're not alone in wanting typed, schema-aware APIs on Mummy — a separate project, Sarcophagus, tackles a similar problem from a different angle: typed request/response encoding across JSON, CBOR, and MessagePack, plus its own Swagger/OpenAPI generation and OAuth2 helpers. Different design choices, same underlying itch in the ecosystem — which suggests this is a real gap worth filling rather than a one-off preference of mine.

Putting It to Use

To validate the fork beyond the bundled examples, I built a small Todo API demo using the typed params, validation, and middleware together, and I'm deploying it live on Render as a working reference — a REST API with real request validation and generated docs, running on a threaded model with no async in sight.

Where This Goes Next

The fork is usable today for anyone building JSON APIs on Mummy who wants documentation and validation that can't silently drift from the actual routes. If you're working in the Nim web space and hit the same "no schema, no docs" wall, I'd genuinely like to hear how you're solving it — feel free to reach out.

Which OpenAPI Codegen Should You Choose? openapi-typescript vs hey-api vs Orval vs Kubb

Wed, 12 Aug 2026 09:22:00 +0000

Hoi hoi!

I'm @nyaomaru, a frontend engineer who thought OpenAPI codegen would make API clients easier, but somehow ended up lost in a forest of generated files.

Writing API clients by hand is painful.

Usually, we want things like:

generated TypeScript types
generated request functions
maybe TanStack Query hooks
maybe MSW mocks
maybe even Zod schemas
and, if possible, everything growing automatically from OpenAPI

That is where OpenAPI codegen tools are useful.

But after comparing several tools with a fairly large real-world schema, I realized something important:

OpenAPI codegen is not only about what a tool can generate.

The generated output itself also matters:

how many files it creates
how fast generation is
how friendly it is to linting
how easy it is for the IDE to index
how errors are modeled
how authentication is handled
how much generated code your team is willing to maintain

In this article, I compared the following four tools:

Tool	Version tested	Main setup
`openapi-typescript`	v7.13.0	types only
`@hey-api/openapi-ts`	v0.96.1	types + SDK + fetch client
`Orval`	v8.8.1	`mode: "tags-split"` / `client: "fetch"`
`Kubb`	v4.37.2	client / types / schemas generated by plugins

The OpenAPI schema used for this comparison was roughly this size. (It was generated by drf-spectacular)

Item	Value
`openapi.yaml` lines	about 75,000
`openapi.yaml` size	about 2 MB
operations	about 1,200

Note: Some endpoint names, schema names, type names, and directory names in this article are simplified or replaced for publication. Also, these libraries move fast, so the generated output and issues described here are based on the versions tested at the time of writing.

For a small API, honestly, any of these tools may work fine.

But at this scale, differences become very visible in generation speed, file count, lint behavior, enum handling, error models, and day-to-day maintainability.

Let's walk through the comparison.

TL;DR

My conclusion is this:

Situation	Tool I would choose
You only need TypeScript types	`openapi-typescript`
You want operationId-based SDK functions and interceptors	`@hey-api/openapi-ts`
You want `TanStack Query`, `Zod`, `MSW`, or `Faker` generated from OpenAPI	`Orval`
You value 1 operation = 1 file and plugin-based codegen architecture	`Kubb`

For my use case, hey-api felt the most practical.

The reasons were simple:

it generates functions from operationId
arguments are consistently shaped like { query, path, body }
it has a result-style error model
it supports axios-like interceptors
the generated output is much lighter than Orval or Kubb
it still leaves room for TanStack Query and Zod plugins later

That said, if your project already uses openapi-typescript + openapi-fetch and you are happy with it, I do not think you need to migrate immediately.

The difference is not huge enough to justify migration by itself.

I would consider switching only when you start feeling pain around SDK functions, interceptors, result handling, mocks, generated hooks, or schema-driven tooling.

In this article, I will call @hey-api/openapi-ts simply hey-api.

Two families of OpenAPI codegen tools

Before comparing each tool one by one, I think it is easier to divide them into two families.

Axis	Family A: thin output, client-focused	Family B: SDK-first, ecosystem generation
Representative tools	`openapi-typescript` / `hey-api`	`Orval` / `Kubb`
Main purpose	accurate types and lightweight runtime	generated SDK + hooks + mocks + validation
Error model	result-style `{ data, error, response }`	wrapper / throw / client-dependent
Output size	small: types only or compact SDK	large: tag-level or operation-level files
Ecosystem features	`TanStack Query` / `Zod` depending on tool	`TanStack Query` / `Zod` / `MSW` / `Faker` / `SWR` etc.
Configuration style	minimal	codegen platform

This distinction is important.

openapi-typescript and Kubb are both OpenAPI codegen tools, but they are not trying to solve the same problem.

openapi-typescript mainly focuses on generating accurate TypeScript types.

Kubb, on the other hand, is closer to a codegen platform that can generate clients, types, schemas, mocks, and other assets in a structured way.

Comparing them directly is a bit like comparing a kitchen knife with a full kitchen. ‍

Both are related to cooking, but they are not the same kind of thing.

️ Generation speed

First, generation speed.

I measured each command three times on WSL2 / Node v24.14 using npx <cmd>. So the numbers include npx startup overhead. (a custom-built PC)

Tool	1st run	2nd run	3rd run	Average	Max RSS
`openapi-typescript`	1.66 s	1.50 s	1.40 s	about 1.5 s	about 335 MB
`@hey-api/openapi-ts`	8.74 s	8.84 s	6.43 s	about 8.0 s	about 495 MB
`Orval`	6.01 s	6.12 s	4.48 s	about 5.5 s	about 415 MB
`Kubb`	17.29 s	19.82 s	17.13 s	about 18.1 s	about 880 MB

Relative to openapi-typescript, the difference looked like this:

Tool	Relative speed
`Orval`	about 3.7x slower
`hey-api`	about 5.3x slower
`Kubb`	about 12x slower

Why openapi-typescript is so fast

In this setup, openapi-typescript only generates types into a single file.

The workflow is basically:

read the schema
convert it into TypeScript types
write one file

That means very little file I/O.

The generated output was just types.gen.ts.

At about 1.5 seconds, it is fast enough that running it in CI, pre-commit, or during local development barely feels like a problem.

Why Kubb is slower

Kubb has a different philosophy.

It splits things much more aggressively.

In this test, I generated operation-level clients, operation-level types, and schemas.

So the cost is not only computation.

The number of files written to disk becomes a major factor.

The structure is clean from a bundling and organization perspective, but with around 1,200 operations, the file system cost becomes noticeable.

For this kind of schema, I would not treat Kubb as something I casually run on every small change unless the generation target is narrowed.

It feels more suitable for a workflow where generated files are committed, generated in CI, or carefully scoped.

Orval was faster than I expected

I expected Orval to be slower.

It can generate things like TanStack Query, Zod, and MSW, so I assumed it would be heavier.

But with tags-split, the main functions are grouped by tag.

In my schema, there were about 25 tags.

So Orval was not generating one giant file, but it also was not generating one file per operation.

That middle ground worked well for speed.

However, this does not mean the output was small.

It still generated more than 2,600 schema files.

️ Output size

Next, generated output size and file count.

Tool	Output	File count	Total size
`openapi-typescript`	`src/api/types.gen.ts`	1	2.4 MB
`@hey-api/openapi-ts`	`src/api/hey-api/`	16	2.9 MB
`Orval`	`src/api/orval/`	2,719	14 MB
`Kubb`	`src/api/kubb/`	3,877	24 MB

Just from these numbers, the tools clearly live in different worlds.

My rough feeling was:

openapi-typescript: one house
hey-api: a small town ️
Orval: a small forest
Kubb: a deep forest

BTW, I love rural life so forest is better.

openapi-typescript

The output was only types.gen.ts.

It contained:

paths
components
operations

One file is simple and easy to understand.

But a 2.4 MB TypeScript file can still be uncomfortable for IDE indexing.

So even though the file count is tiny, the single file itself is large.

hey-api

hey-api generated 16 files.

The main files looked like this:

File	Purpose
`types.gen.ts`	request / response types
`sdk.gen.ts`	generated operation functions
`index.ts`	barrel exports
`client.gen.ts`	default client instance
`client/`	fetch client implementation
`core/`	auth, serializers, utils, etc.

types.gen.ts was about 1.7 MB, and sdk.gen.ts was about 750 KB.

With 1,200 operations, the SDK file naturally becomes large.

But compared with Orval and Kubb, the output still felt manageable.

Orval

I used Orval with tags-split.

The structure looked roughly like this:

src/api/orval/
├─ schemas/
│  ├─ ordersWriteRequest.ts
│  ├─ ordersListParams.ts
│  └─ ...
├─ order/
│  └─ order.ts
├─ product/
│  └─ product.ts
└─ ...

Functions were grouped by tag.

In this schema:

tag files: about 25
schema files: more than 2,600

The largest generated file was around 30,000 lines.

Kubb

Kubb generated an even more split structure.

src/api/kubb/
├─ types/
├─ clients/
├─ schemas/
└─ index.ts

Directory	Purpose
`types/`	operation-level types
`clients/`	operation-level functions
`schemas/`	individual schemas
`index.ts`	barrel exports

The nice part is that the structure is close to 1 operation = 1 file.

That makes grep easy and can be friendly to tree-shaking.

But the tradeoff is real:

large PR diffs
heavier IDE indexing
slower clone and checkout
more generated files to commit or ignore

Calling the same endpoint

Now let's compare the actual call sites.

Assume this endpoint:

GET /orders

It accepts common list query parameters like page and page_size.

openapi-typescript

openapi-typescript only generates types, so I used it with openapi-fetch.

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

const client = createClient<paths>({
  baseUrl: "http://localhost:8000",
});

const { data, response } = await client.GET("/orders", {
  params: {
    query: {
      page: 1,
      page_size: 20,
    },
  },
});

The important part is that the endpoint is specified as a path string:

client.GET("/orders");

This is simple and readable.

IDE autocomplete also works well.

But it is not operationId-based, so if the endpoint changes, rename refactoring is not as direct as function-based clients.

hey-api

hey-api generates SDK functions.

import { ordersList } from "./api/hey-api/sdk.gen";

const { data, response } = await ordersList({
  query: {
    page: 1,
    page_size: 20,
  },
});

The function name comes from operationId.

I like this because you can grep by function name and use IDE rename refactoring more naturally.

The argument shape is also consistent:

{
  query,
  path,
  body,
}

This consistency becomes useful later when building wrappers, logging, retries, auth handling, or tracing.

Orval

For Orval, I used fetch, tags-split, and useNamedParameters: true.

import { ordersList } from "./api/orval/orders/order";

const { data, status, headers } = await ordersList({
  page: 1,
  page_size: 20,
});

The return value is like:

{
  data,
  status,
  headers,
}

At first glance, this is easy to use.

But with the default fetch client, 4xx and 5xx responses are not thrown as errors.

That point is very important in real applications.

Kubb

Kubb generates operation-level functions.

import { ordersList } from "./api/kubb/clients/ordersList";

const data = await ordersList({
  page: 1,
  page_size: 20,
});

On success, it returns the response data directly.

So the call site is very short.

However, if you want to access response headers or status, the default return shape may not be enough.

Also, path parameters and body arguments can become positional depending on the endpoint, which can make generic wrappers harder to design.

️ Path params and body arguments

A list endpoint does not show all differences, so let's compare path params and body arguments too.

GET by id

// openapi-typescript
const { data } = await client.GET("/orders/{id}", {
  params: {
    path: {
      id: "123",
    },
  },
});

// hey-api
const { data } = await ordersRetrieve({
  path: {
    id: "123",
  },
});

// Orval
const { data } = await ordersRetrieve({
  id: "123",
});

// Kubb
const data = await ordersRetrieve("123");

Summary:

Tool	Path param style
`openapi-typescript`	`params.path`
`hey-api`	`{ path: { id } }`
`Orval`	`{ id }`
`Kubb`	positional argument like `"123"`

Kubb is short.

But if an endpoint has multiple path params, positional arguments grow like (id1, id2, ...).

This is partly a preference issue, but for large API clients I usually prefer named object arguments.

POST body

// openapi-typescript
await client.POST("/orders", {
  body,
});

// hey-api
await ordersCreate({
  body,
});

// Orval
await ordersCreate(body);

// Kubb
await ordersCreate(body);

Orval and Kubb feel natural when the body is the first argument.

But for POST endpoints without a body, this can sometimes lead to explicit undefined arguments.

hey-api and openapi-typescript add one level with { body }, but the shape remains consistent with query and path.

For a large application, I personally prefer the consistency of hey-api.

Function signature philosophy

Here is the broader comparison of call signatures.

Axis	`openapi-typescript`	`hey-api`	`Orval`	`Kubb`
endpoint selection	URL string	operationId function	operationId function	operationId function
query	`params.query`	`{ query }`	first argument	first argument
path	`params.path`	`{ path }`	`{ id }` or positional	positional
body	`{ body }`	`{ body }`	first argument	first argument
headers	options / middleware	options / interceptor	`RequestInit`	config
cross-cutting behavior	middleware	interceptor	mutator	config / custom client

The key strength of hey-api is that every endpoint moves toward the same shape:

await api({
  query,
  path,
  body,
  headers,
});

That makes cross-cutting behavior easier:

authentication
logging
retries
trace ids
request ids
custom headers

Orval and Kubb often produce shorter call sites, but signatures can vary more by endpoint.

In a small codebase, that is probably fine.

In a 1,200-operation API, consistency matters a lot more.

⚠️ Error model

This was one of the most important differences.

Tool	Default behavior	Can be changed?
`openapi-typescript` + `openapi-fetch`	`{ data, error, response }` result union	can throw via middleware
`hey-api`	`{ data, error, response }` result union	can throw with `throwOnError: true`
`Orval`	wrapper like `{ data, status, headers }`	can throw with custom fetch / mutator / config
`Kubb`	success returns `data`, failure throws	customizable via client

Result union in openapi-typescript and hey-api

With openapi-fetch and hey-api, non-2xx responses can be represented in error if the OpenAPI schema defines them.

But in my drf-spectacular schema, most non-2xx responses were not described.

So in practice, error was often close to never.

That means I still need a runtime check like this:

const { data, response } = await client.GET("/orders", {
  params: {
    query: {
      page: 1,
    },
  },
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

return data;

With hey-api, I can also opt into throwing behavior per call:

const { data } = await ordersList({
  query: {
    page: 1,
  },
  throwOnError: true,
});

I like having both options.

Sometimes I want a result-style response.

Sometimes I want HTTP errors to throw immediately.

Orval's default fetch behavior needs attention

With Orval's default fetch client, 4xx and 5xx responses do not throw automatically.

const res = await ordersList({
  page: 1,
});

if (res.status !== 200) {
  throw new Error(`HTTP ${res.status}`);
}

return res.data;

If the team forgets to check status, it is possible to treat an error response as if it were success data.

For example, the code may try to access data.results and then fail at runtime because the actual response body was an error shape.

This is easy to miss if you only look at TypeScript types.

If I used Orval in production, I would choose one of these patterns:

always check status at the call site
configure the fetch client with override.fetch.forceSuccessResponse: true
use override.mutator and write a custom fetch wrapper for auth, refresh, and errors

A custom fetch may look like this:

// custom-fetch.ts
export const customFetch = async <T>(
  url: string,
  options: RequestInit,
): Promise<T> => {
  const res = await fetch(url, options);

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }

  return res.json();
};

Orval is powerful, but this behavior should be made explicit as a team rule.

Kubb's throw model

Kubb is closer to a throw-based model by default.

const data = await ordersList({
  page: 1,
});

On success, you get the data directly.

On failure, it throws.

This is pleasant in UI code.

But if you need response metadata, such as:

Retry-After
ETag
rate limit headers
pagination headers

then the default return value may not be enough, and you may need a custom client or wrapper.

✅ Authentication and interceptors

Authentication handling also differs quite a bit.

openapi-fetch

openapi-fetch supports middleware.

client.use({
  onRequest: ({ request }) => {
    request.headers.set("Authorization", `Bearer ${getToken()}`);
    return request;
  },
});

If you already use openapi-typescript + openapi-fetch, this is clean and lightweight.

hey-api

hey-api has axios-like interceptors.

client.interceptors.request.use((request) => {
  request.headers.set("Authorization", `Bearer ${getToken()}`);
  return request;
});

This API feels familiar.

For common headers, logging, trace ids, and 401 refresh flows, this style is easy to work with.

Generated hey-api functions can also include security metadata.

export const ordersList = <ThrowOnError extends boolean = false>(
  options?: Options<ordersListData, ThrowOnError>,
) =>
  (options?.client ?? client).get<ordersListResponses, unknown, ThrowOnError>({
    security: [{ scheme: "bearer", type: "http" }],
    url: "/orders",
    ...options,
  });

This is a little more to understand at first, but useful for authenticated APIs.

Orval

Orval is closer to raw fetch.

await ordersList(
  { page: 1 },
  {
    headers: {
      Authorization: `Bearer ${getToken()}`,
    },
  },
);

You can pass headers per call.

But in a real app, I would usually create a custom fetch with override.mutator.

Kubb

Kubb can configure the client or accept per-call config.

client.setConfig({
  baseURL: "http://localhost:8000",
});

Headers can also be passed per call.

await ordersList(
  { page: 1 },
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  },
);

But it does not feel like axios-style interceptors are the default mental model.

For things like 401 refresh, I would expect to wire my own client behavior.

TanStack Query, Zod, MSW, and Faker

This is where the second family of tools becomes attractive.

Feature	`openapi-typescript`	`hey-api`	`Orval`	`Kubb`
Type generation	Good	Good	Good	Good
Fetch client	external `openapi-fetch`	Good	Good	Good
TanStack Query	No	plugin	Good	plugin
Zod	No	plugin	Good	plugin
MSW	No	limited / roadmap-dependent	Good	Good
Faker	No	No	Good	Good
SWR / Vue Query	No	limited	Good	limited / plugin-dependent

Orval has strong built-in support around this area.

It can target tools like:

TanStack Query
SWR
Vue Query
Zod
MSW
Faker

Kubb also has a strong plugin-based approach.

hey-api is more focused around SDK generation, TanStack Query, and Zod.

If your goal is mainly API clients and types, openapi-typescript or hey-api may be enough.

If your goal is to generate a broader frontend ecosystem from OpenAPI, Orval or Kubb becomes more interesting.

In my case, I did not need MSW or Faker yet.

So Orval and Kubb felt a bit too much for the current problem.

Enum issue: drf-spectacular BlankEnum

One very real-world issue was enum generation.

drf-spectacular can represent nullable or blank enum values like this:

BlankEnum:
  enum: [""]

NullEnum:
  enum: [null]

Then a field may use anyOf like this:

status:
  anyOf:
    - $ref: "#/components/schemas/StatusEnum"
    - $ref: "#/components/schemas/BlankEnum"
    - $ref: "#/components/schemas/NullEnum"
  nullable: true

The intended TypeScript value is something like:

"WAITING" | "RUNNING" | "SUCCESS" | "FAILURE" | "" | null;

Generated BlankEnum

The generated output differed by tool.

// openapi-typescript
BlankEnum: "";

// hey-api
export enum BlankEnum {
  "" = "",
}

// Orval
export type BlankEnum = (typeof BlankEnum)[keyof typeof BlankEnum];

export const BlankEnum = {
  "": "",
} as const;

// Kubb
export const blankEnumEnum = {} as const;
export type BlankEnumEnumKey =
  (typeof blankEnumEnum)[keyof typeof blankEnumEnum];

export type BlankEnum = BlankEnumEnumKey;

In Kubb, the empty string disappeared, and the type effectively became never.

What happens after anyOf composition

As a result, only Kubb dropped "" from the final type.

Tool	Can represent `""` in the type?
`openapi-typescript`	Yes
`hey-api`	Yes
`Orval`	Yes
`Kubb`	No

This is not just a small type detail.

It can break real application code if fields like status, file_type, or update_type actually receive an empty string from the backend.

Possible workarounds are:

patch BlankEnum after generation
cast affected fields to string | null
wait for an upstream fix
avoid this schema shape if you control the backend

If you use drf-spectacular and have many BlankEnum / NullEnum patterns, I recommend checking this before adopting Kubb.

Body type reusability

POST body types also differed.

Tool	Body type style
`openapi-typescript`	`components["schemas"]["ordersWriteRequest"]`
`hey-api`	`ordersWriteRequest`
`Orval`	`ordersWriteRequest`
`Kubb`	`ordersCreateMutationRequest`

Kubb generated endpoint-scoped wrapper types.

This can be good because each operation is very explicit.

But if you want to reuse the same schema in app-level code, it can be a little less convenient.

For example, if a form wants to use ordersWriteRequest as its submit data type, openapi-typescript, hey-api, and Orval feel more natural.

With Kubb, I may need to alias the operation-scoped type:

import type { ordersCreateMutationRequest } from "./api/kubb/types/ordersCreate";

type OrderWriteRequest = ordersCreateMutationRequest;

This is not wrong.

It just depends on whether your app wants shared schema types or operation-scoped types.

Lint behavior

All four tools passed tsc --noEmit.

But linting showed differences.

Tool	oxlint + `no-explicit-any`	eslint recommended
`openapi-typescript`	0	36
`hey-api`	0	57
`Orval`	0	36
`Kubb`	1,549	1,585

openapi-typescript / hey-api / Orval lint errors

For the first three tools, the eslint errors were mainly no-irregular-whitespace.

In my schema, some Django docstrings contained full-width spaces.

Those comments were copied into generated code, and eslint complained.

This is more about source docstrings and lint configuration than generated code quality.

It can usually be handled by:

skipping comments
excluding generated files from lint
adding lint overrides for generated code

Kubb lint errors

Kubb produced many no-explicit-any errors.

Most were in the runtime client side.

This does not mean Kubb is unusable.

But if generated files are included in lint, Kubb almost certainly needs ignore rules or overrides.

Before adopting it, I would decide:

will generated files be committed?
will generated files be linted?
will generated files be checked in CI?
which rules are disabled for generated code?

Configuration notes

Here are some issues I hit while setting up each tool.

openapi-typescript

This was the easiest setup.

A single CLI command worked well.

I did not hit any major configuration problems.

hey-api

hey-api uses openapi-ts.config.ts.

I hit a few small points:

output.format: "prettier" aborts if Prettier is not installed
runtimeConfigPath is emitted as an import path relative to output.path

I initially assumed runtimeConfigPath was relative to the project root.

That was easy to misunderstand.

I shared this with the author, and the related PR was merged the next day.

That fast response was a positive signal for adoption.

Orval

Orval uses orval.config.ts.

It can split outputs by target, which is useful if you want to generate SDKs, Zod schemas, MSW mocks, and other assets separately.

I did not hit major setup issues.

But if you care about auth, refresh, or error handling, you should understand override.mutator early.

Kubb

Kubb configuration is plugin-based.

Depending on your environment, generated imports with .ts extensions may require this tsconfig setting:

{
  "compilerOptions": {
    "allowImportingTsExtensions": true
  }
}

This is not necessarily bad, but it should match your TypeScript and bundler policy.

I had to adjust the setup a few times.

️ My impression of openapi-typescript

openapi-typescript is the thinnest and fastest option.

It generates types and lets you choose the runtime layer yourself, often with openapi-fetch.

What I liked:

very fast generation
simple setup
small generated output
strong focus on type correctness
runtime is separate and flexible

What may be missing:

no generated SDK functions
endpoint calls are path-string based
weaker fit for operationId-based rename refactoring
TanStack Query, Zod, and MSW need separate handling

If you value simplicity, this is very strong.

Especially if codegen runs often in local development or CI, the speed is a real advantage.

️ My impression of hey-api

hey-api felt like the best balance for my use case.

It is thicker than openapi-typescript, but much lighter than Orval or Kubb.

What I liked:

generated SDK functions
consistent { query, path, body } arguments
axios-like interceptors
result model and throwOnError option
shared schema types are easy to use
generated output remains manageable

Weak points:

generation takes longer than openapi-typescript
sdk.gen.ts can become large
weaker than Orval / Kubb for MSW and Faker
NullEnum may degrade into an empty enum in some cases

In my case, NullEnum was not a major practical issue because nullable fields still carried nullable: true through the composed type.

More importantly, BlankEnum preserved the empty string correctly.

For my needs:

I wanted operationId functions
I wanted interceptors
I wanted result-style handling
I did not need generated MSW or Faker yet

So hey-api was the most practical choice.

️ My impression of Orval

Orval is strong if you want OpenAPI to generate a broader frontend layer.

What I liked:

supports TanStack Query, SWR, and Vue Query
can generate Zod
can generate MSW and Faker
can split outputs by target
faster than Kubb in this test
shared body schemas are easy to reuse

Things to watch:

default fetch client does not throw on 4xx / 5xx
auth and refresh usually require a mutator
file count can be large
tag files can become large
NullEnum may degrade into an empty const

If you only want an API client, Orval may feel too thick.

But if you want generated hooks, validation schemas, mocks, and test data, Orval becomes much more attractive.

If I moved deeper into the ecosystem-generation side, I would probably evaluate Orval first.

️ My impression of Kubb

Kubb has a strong philosophy.

What I liked:

close to 1 operation = 1 file
friendly to grep and physical file navigation
structure can be tree-shake friendly
clear plugin-based architecture
can expand into MSW, Faker, TanStack Query, Zod, etc.
gives strong control over the codegen pipeline

What felt heavy in this schema:

slow generation
3,877 files / 24 MB output
many lint errors from any
possible .ts import extension requirements
positional path params make wrappers harder
body types are endpoint-scoped
BlankEnum became never and lost the empty string

Kubb is not a bad tool.

Actually, I like its design philosophy.

But if your main goal is simply "I want a type-safe API client for a normal frontend app," it may be too heavy as the first option.

I would choose Kubb when I have a clear reason, such as:

I strongly want 1 operation = 1 file
I want to design my own codegen pipeline
I want plugin-level control
I want to unify clients, schemas, mocks, and test data through plugins

The potential is high, but it needs commitment.

Summary table

Axis	`openapi-typescript`	`hey-api`	`Orval`	`Kubb`
Family	A: type-focused	A: lightweight SDK	B: frontend asset generation	B: plugin/codegen platform
Generation time	1.5s	8.0s	5.5s	18.1s
Output files	1	16	2,719	3,877
Output size	2.4 MB	2.9 MB	14 MB	24 MB
Generates functions	No	Yes	Yes	Yes
Function split	none	one SDK file	one file per tag	one file per operation
Error model	result union	result union / throw	success wrapper	throw
Client object	external library	generated client	raw fetch / mutator	generated client
Interceptor	openapi-fetch middleware	axios-like	mutator	config / custom client
Path params	`params.path`	`{ path: { id } }`	`{ id }`	positional
Body type	shared schema	shared schema	shared schema	endpoint-scoped
TanStack Query	No	plugin	built-in support	plugin
Zod	No	plugin	built-in support	plugin
MSW / Faker	No	limited	strong	strong
Lint	minor adjustment	minor adjustment	minor adjustment	likely needs ignore/override
drf-spectacular BlankEnum	OK	OK	OK	needs care
Best fit	thin and safe	SDK + interceptors	generate frontend assets	design codegen pipeline

How I would choose

After this comparison, I would choose like this.

1. Start with openapi-typescript

If your project already works well with openapi-typescript + openapi-fetch, I would stay there.

It is fast, thin, and easy to understand.

A small wrapper like src/api/client.ts plus middleware-based auth may be enough.

There is no need to move to heavier codegen unless you have a concrete pain.

2. Move to hey-api when SDK functions become useful

The next step is usually wanting things like:

call APIs by operationId functions instead of URL strings
grep by function name
use rename refactoring
handle auth and refresh with interceptors
work with consistent endpoint options

At that stage, hey-api is a very good fit.

3. Use Orval when OpenAPI becomes the source of frontend assets

If OpenAPI becomes more than API client generation, Orval becomes strong.

For example:

generated TanStack Query hooks
generated Zod schemas
generated MSW mocks
generated fake data
multiple generation targets

This is where Orval's value becomes much clearer.

4. Choose Kubb when you love the architecture

Kubb is powerful.

But at this schema size, it was also heavy.

I would choose it when I strongly care about:

1 operation = 1 file
plugin architecture
tree-shake-friendly structure
codegen pipeline control
generating many kinds of artifacts consistently

It may not be my first choice for a normal frontend app, but it is very interesting if you want to design codegen itself.

Final conclusion

OpenAPI codegen should not be chosen only by asking:

Which tool has the most features?

A better question is:

How much generated code are we willing to own?

My final choice looks like this:

Goal	Choice
I only want types	`openapi-typescript`
I want SDK functions and interceptors	`hey-api`
I want to generate frontend assets together	`Orval`
I want to control codegen structure and plugins	`Kubb`

For my current project, hey-api had the best balance of SDK functions, interceptors, result handling, and output size.

The more useful codegen becomes, the bigger the generated forest becomes.

So the important question is:

Who maintains that forest, how much of it, and with what team rules?

That is the real OpenAPI codegen decision.

What does your team generate from OpenAPI?

Only types?
SDK functions?
Hooks?
Mocks?

or the whole forest?

Running OpenAPI Validation in GitHub Actions and Showing Findings in Pull Requests

Sat, 04 Jul 2026 00:49:15 +0000

Hello, I'm Ganesh. I'm building git-lrc, an AI code reviewer that runs on every commit. It is free, unlimited, and source-available on Github. Star git-lrc on GitHub to help more developers discover the project. Do give it a try and share your feedback for improving the product.

In a previous article, I explained what SARIF is and why many security and quality tools use it as a common reporting format.

In this article, we'll focus on a practical example: validating an OpenAPI specification in GitHub Actions and displaying findings directly inside GitHub Pull Requests.

By the end, you'll have a workflow that:

Lints your OpenAPI specification
Generates a SARIF report
Uploads results to GitHub Code Scanning
Shows annotations directly in Pull Requests

Sample OpenAPI Specification

Let's start with a simple OpenAPI file that contains a deliberate issue.

openapi: 3.0.3

info:
  title: User API
  version: 1.0.0

paths:
  /users/{id}:
    get:
      operationId: getUserById

      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string

      responses:
        "200":
          description: User found

Notice that the path is:

/users/{id}

but the parameter is named:

userId

The parameter name should match the path placeholder (id).

We'll use this mistake to verify that our workflow correctly reports findings.

Installing Spectral

For this example, we'll use Spectral, one of the most popular OpenAPI linting tools.

npm install -g @stoplight/spectral-cli

Run it locally:

spectral lint openapi.yaml

You should see an error related to the path parameter mismatch.

Generating a SARIF Report

Instead of printing results to the console, we can generate a SARIF report:

spectral lint openapi.yaml \
  --format sarif \
  --output results.sarif

This produces:

results.sarif

which GitHub can consume directly.

GitHub Actions Workflow

Create:

.github/workflows/openapi.yml

name: OpenAPI Validation

on:
  pull_request:

permissions:
  contents: read
  security-events: write

jobs:
  openapi:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli

      - name: Generate SARIF Report
        run: |
          spectral lint openapi.yaml \
            --format sarif \
            --output results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

How It Works

The workflow performs four simple steps:

Checks out the repository
Installs Spectral
Generates a SARIF report
Uploads the SARIF report to GitHub

The upload step is handled by GitHub's official SARIF uploader:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Once uploaded, GitHub automatically processes the findings.

Viewing Results in Pull Requests

After opening a Pull Request, GitHub analyzes the uploaded SARIF report and associates findings with the corresponding files and lines.

For our example, GitHub highlights the parameter definition and reports something similar to:

Path parameter "id" is not defined.
Expected parameter name "id" but found "userId".

Developers can review the issue directly from the Pull Request without searching through GitHub Action logs.

Why I Prefer This Approach

Many teams fail OpenAPI validation jobs and require developers to inspect CI logs.

While this works, it doesn't scale well when repositories contain multiple specifications or many validation rules.

Uploading SARIF results provides:

Inline annotations
Better visibility during code review
Centralized findings in GitHub Code Scanning
Consistent reporting across different tools

The same workflow can later be extended to include security scanners, secret scanners, IaC scanners, and custom validation tools.

Conclusion

Integrating OpenAPI validation into GitHub Actions is straightforward. With Spectral generating SARIF output and GitHub handling the presentation layer, developers receive feedback exactly where they are already reviewing code: inside the Pull Request.

If your organization already uses SARIF for other security or quality tools, OpenAPI validation can fit naturally into the same workflow with only a few lines of configuration.

Any feedback or contributors are welcome! It’s online, source-available, and ready for anyone to use.

⭐ Star git-lrc on GitHub