createRoute — declare an OpenAPI route

Imported from the facade: import { createRoute, z, jsonContent, HttpStatusCodes } from "@/framework/facade.js".

Declares a fully documented route — path, method, tags, request (params/query/body) and response schemas — that createRouter().api() mounts and the OpenAPI spec renders. See Routing and OpenAPI.

Signature

Function	Signature	Description
createRoute	(args: RouteConfig) => RouteConfig	Declare an OpenAPI route with request/response schemas

Use cases

Basic route

Hono

import {
  createRoute,
  group,
  HttpStatusCodes,
  jsonContent,
  z,
} from "@/framework/facade.js";

const listRoute = createRoute({
  path: "/",
  method: "get",
  tags: ["Posts"],
  summary: "List all posts",
  responses: {
    [HttpStatusCodes.OK]: jsonContent(z.array(PostSchema), "list of posts"),
  },
});

export default group().api(listRoute, async (c) => c.json(await listPosts()));

Express

import {
  createRoute,
  group,
  HttpStatusCodes,
  jsonContent,
  z,
} from "@/framework/facade.js";

const listRoute = createRoute({
  path: "/",
  method: "get",
  tags: ["Posts"],
  summary: "List all posts",
  responses: {
    [HttpStatusCodes.OK]: jsonContent(z.array(PostSchema), "list of posts"),
  },
});

export default group().api(listRoute, async (_req, res) =>
  res.json(await listPosts()),
);

Request bodies & params

const storeRoute = createRoute({
  path: "/",
  method: "post",
  tags: ["Posts"],
  request: { body: jsonContent(CreatePostSchema, "post data") },
  responses: {
    [HttpStatusCodes.CREATED]: jsonContent(PostSchema, "created post"),
  },
});

const showRoute = createRoute({
  path: "/{id}",
  method: "get",
  tags: ["Posts"],
  request: {
    params: z.object({ id: z.coerce.number().openapi({ example: 1 }) }),
  },
  responses: {
    [HttpStatusCodes.OK]: jsonContent(PostSchema, "post details"),
    [HttpStatusCodes.NOT_FOUND]: { description: "Post not found" },
  },
});

Real world — the auth router

// modules/auth/routes/api.ts
const loginRoute = createRoute({
  path: "/login",
  method: "post",
  tags: ["Auth"],
  request: { body: jsonContent(LoginSchema, "Login payload") },
  responses: {
    [HttpStatusCodes.OK]: jsonContent(AuthResponseSchema, "Logged in"),
  },
});

Notes

• createRoute is exported from the facade on both engines (from @hono/zod-openapi on Hono; a passthrough over ExpressRouteConfig from @asteasolutions/zod-to-openapi on Express). It pairs with the facade's z — see z for .openapi().
• Requires OPEN_API=true to drive the Scalar UI at /api-docs.
• Mount it with createRouter().api(route, handler) or group().api(route, handler) — see createRouter.