Route metadata

Routes provide metadata that @hectoday/openapi uses to generate the spec. The request schemas are the primary source of information. You can also add response schemas for documentation.

request

Zod schemas for request validation. Used both at runtime (validation) and for spec generation.

route.post("/books/:id", {
  request: {
    params: z.object({ id: z.uuid() }),
    query: z.object({
      dryRun: z.coerce.boolean().default(false),
    }),
    body: z.object({
      title: z.string().min(1).max(200),
      genre: z.enum(["fiction", "non-fiction"]),
    }),
  },
  resolve: (c) => {
    /* ... */
  },
});

In the generated spec:

• body becomes requestBody with a JSON schema
• query becomes parameters with in: "query"
• params becomes parameters with in: "path"

Path parameters defined with :param syntax are automatically converted to OpenAPI {param} format. If you do not provide a params schema, the path parameters are still included in the spec as plain strings.

response

Zod schemas for response documentation, keyed by HTTP status code. Does NOT validate outgoing responses at runtime.

route.get("/books/:id", {
  request: { params: z.object({ id: z.uuid() }) },
  response: {
    200: z.object({
      id: z.uuid(),
      title: z.string(),
      author: z.object({ id: z.string(), name: z.string() }),
    }),
    404: z.object({
      error: z.object({
        code: z.string(),
        message: z.string(),
      }),
    }),
  },
  resolve: (c) => {
    /* ... */
  },
});

Each key is a status code, and the value is a Zod schema describing the response body for that status. Status codes like 204 that do not have a body will omit the content in the spec.

If no response is provided, the route gets a default 200 OK response in the spec.

Complete example

route.post("/books", {
  request: {
    body: CreateBookSchema,
  },
  response: {
    201: BookSchema,
    400: ErrorSchema,
  },
  resolve: (c) => {
    if (!c.input.ok) {
      return Response.json(
        { error: { code: "VALIDATION_ERROR", message: "Invalid input" } },
        { status: 400 },
      );
    }
    const book = createBook(c.input.body);
    return Response.json(book, { status: 201 });
  },
});

This produces a spec entry with: the path /books, method POST, request body schema from CreateBookSchema, a 201 response with BookSchema, and a 400 response with ErrorSchema.