Adding OpenAPI Support to Mummy, a Nim HTTP Framework

Nim doesn't have a lot of options for building HTTP APIs with the kind of
batteries-included developer experience you get in frameworks like FastAPI or
Express with Swagger middleware. mummy is a
fast, solid HTTP/WebSocket server library for Nim (my fork with the
additions below is at
github.com/isaiahpeter/mummy) — but out of the box, it
doesn't generate OpenAPI specs, validate request bodies, or give you typed
path parameters. So I forked it and added those.

This post walks through what I built, why, and what I learned extending an
existing Nim library instead of starting from scratch.

Why mummy, and why OpenAPI

I wanted a Nim backend for a few projects (a contact-form API, a todo API
demo) and kept missing three things I'd take for granted in other
ecosystems:

• Auto-generated API docs — a /docs endpoint you can actually hand to someone, generated from your routes instead of hand-written.
• Typed path parameters — pulling id out of /users/{id} as an int without manual parsing and error handling in every handler.
• Request validation — rejecting a bad JSON body before it reaches your handler logic, with a schema to back it up.

mummy is fast and minimal by design, which is exactly why it was worth
extending rather than replacing.

What I added

OpenAPI spec generation. I added openapi_schema.nim and
openapi_router.nim, which let you wrap routes in an OpenApiRouter and
attach a summary, tags, and a response schema via schemaOf. The router
serves both /openapi.json and a browsable /docs page generated from your
actual route definitions — so the docs can't drift out of sync with the code
the way hand-written API docs do.

Typed path parameters. pathParam[T](request, "id") pulls a path
segment and parses it as the type you ask for, with a clean 400 response if
parsing fails. One gotcha worth flagging if you try this yourself: in this
Nim version, the generic dot-call form (request.pathParam[int]("id"))
doesn't parse — you have to call it as pathParam[int](request, "id")
instead.

Request body validation. parseValidatedBody[T] checks an incoming JSON
body against the schema generated by schemaOf, and returns a 400 with a
clear error message on mismatch, instead of letting a malformed body reach
your handler and fail in some less obvious way further down.

Composable middleware. A Middleware type and a use() method on
OpenApiRouter, plus a couple of built-ins — loggingMiddleware and
bearerAuthMiddleware — so cross-cutting concerns don't have to be copy-pasted
into every handler.

Migrating the examples

mummy ships with 12 example servers. I migrated all of them to the new
OpenApiRouter to sanity-check the additions against real, varied code
instead of just a toy case. That surfaced a few real bugs I wouldn't have
caught otherwise:

• One example declared a requestBody schema for a route whose handler never actually read a JSON body — leftover from copy-pasting between examples. Easy to miss, misleading if it ships in generated docs.
• The WebSocket example used a wildcard route (/*) for channel names. I converted it to a named path parameter (@channel), which also fixed a latent bug: the original handler read request.uri, which can include a ?query string, instead of the clean decoded path.

Only one example actually declared response schemas, and those checked out
correctly — the rest use the router's default 200 OK, which needed no
changes.

What's next

I'm using this fork to build a small todo API demo (deployed on Render) as a
live, working example of the OpenAPI/validation/middleware features
together, and a contact-form microservice for my own site. Both are useful
proof that the additions hold up outside of the example suite they were
tested against.

If you're working in Nim and have hit the same "no OpenAPI docs, no request
validation" gap with mummy or another minimal framework, I'd be curious to
hear how you've worked around it — or if you want to look at the fork
yourself, it's at github.com/isaiahpeter/mummy.