Starter Code REST API with Auto-Generated Swagger UI & Complete Auth Flow

[SyahrulBhudiF]

I’d like to share something I built in my free time a REST API starter template to help kickstart projects quickly.

link : https://github.com/SyahrulBhudiF/Hono-Starter-Code

In this template, I’m using Hono as the web framework, along with Drizzle ORM for database management, PostgreSQL, Redis for caching, and JWT/OAuth2 for authentication.

For the features, it includes:

• Authentication with JWT, OAuth2(Google), and Email Validation (OTP)
• Database integration with Drizzle ORM & PostgreSQL
• Caching with Redis
• Docker for easy development and deployment
• Auto-generated API documentation with OpenAPI & SwaggerUI

Improving SwaggerUI in Hono and validation

I also wanted to improve how SwaggerUI is generated in Hono. While Hono provides a built-in method for generating OpenAPI documentation, manually writing routes repeatedly can be quite tedious.

To solve this, I created a utility function that simplifies the process of defining API routes with OpenAPI specifications. This function allows you to generate endpoints dynamically while keeping the Swagger documentation structured, clean and auto zod validation.

Here’s the helper function I made:

import { createRoute, OpenAPIHono } from "@hono/zod-openapi";
import { z, ZodType } from "zod";

export const createRouteUtil = (option: {
  method: "post" | "get" | "put" | "patch" | "delete",
  path: string,
  tags: string[],
  responseSchema: ZodType,
  requestSchema?: ZodType,
  security?: Parameters<typeof createRoute>[0]['security'],
  description?: string,
}) => {
  return createRoute({
    method: option.method,
    path: option.path,
    description: option.description,
    tags: option.tags,
    security: option.security,
    ...(option.requestSchema
      ? {
          request: {
            body: {
              content: {
                "application/json": {
                  schema: option.requestSchema,
                },
              },
            },
          },
        }
      : {}),
    responses: {
      200: {
        description: "Success",
        content: {
          "application/json": {
            schema: option.responseSchema,
          },
        },
      },
      400: {
        description: "Bad Request",
        content: {
          "application/json": {
            schema: z.object({
              status: z.string(),
              message: z.string(),
              data: z.null(),
            }),
            example: {
              status: "error",
              message: "Invalid request data",
              data: null,
            },
          },
        },
      },
      401: {
        description: "Unauthorized",
        content: {
          "application/json": {
            schema: z.object({
              status: z.string(),
              message: z.string(),
              data: z.null(),
            }),
            example: {
              status: "error",
              message: "Unauthorized access",
              data: null,
            },
          },
        },
      },
      403: {
        description: "Forbidden",
        content: {
          "application/json": {
            schema: z.object({
              status: z.string(),
              message: z.string(),
              data: z.null(),
            }),
            example: {
              status: "error",
              message: "Access forbidden",
              data: null,
            },
          },
        },
      },
      404: {
        description: "Not Found",
        content: {
          "application/json": {
            schema: z.object({
              status: z.string(),
              message: z.string(),
              data: z.null(),
            }),
            example: {
              status: "error",
              message: "Resource not found",
              data: null,
            },
          },
        },
      },
      500: {
        description: "Internal Server Error",
        content: {
          "application/json": {
            schema: z.object({
              status: z.string(),
              message: z.string(),
              data: z.null(),
            }),
            example: {
              status: "error",
              message: "Internal server error",
              data: null,
            },
          },
        },
      },
    },
  });
};

How to use it

import {createRouteUtil} from "../util/route-util";
import {any, z} from "zod";
import {AuthValidation} from "../validation/auth-validation";

export const registerRoute = createRouteUtil({
    method: "post",
    path: "/register",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.object({
            email: z.string(),
            name: z.string(),
        }),
    }),
    requestSchema: AuthValidation.REGISTER,
    description: "Register a new user",
});

export const sendOTPRoute = createRouteUtil({
    method: "post",
    path: "/send-otp",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.null(),
    }),
    requestSchema: AuthValidation.SEND_OTP,
    description: "Send OTP to the user",
});

export const verifyOTPRoute = createRouteUtil({
    method: "post",
    path: "/verify-otp",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.null(),
    }),
    requestSchema: AuthValidation.VERIFY_OTP,
    description: "Verify OTP of the user",
});

export const loginRoute = createRouteUtil({
    method: "post",
    path: "/login",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.object({
            email: z.string().email(),
            name: z.string(),
            role: z.string(),
            accessToken: z.string(),
            refreshToken: z.string()
        }),
    }),
    requestSchema: AuthValidation.LOGIN,
    description: "Login to the application"
});

export const logoutRoute = createRouteUtil({
    method: "post",
    path: "/logout",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.null(),
    }),
    requestSchema: z.object({
        refreshToken: z.string(),
    }),
    security: [{BearerAuth: []}],
    description: "Logout from the application",
});

export const resetPasswordRoute = createRouteUtil({
    method: "post",
    path: "/reset-password",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.null(),
    }),
    requestSchema: AuthValidation.RESET_PASSWORD,
    description: "Reset password of the user",
});

export const googleLoginRoute = createRouteUtil({
    method: "get",
    path: "/google",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.object({
            email: z.string().email(),
            name: z.string(),
            role: z.string(),
            accessToken: z.string(),
            refreshToken: z.string()
        }),
    }),
    description: "Login with google",
});

export const refreshTokenRoute = createRouteUtil({
    method: "post",
    path: "/refresh-token",
    tags: ["Auth"],
    responseSchema: z.object({
        status: z.string(),
        message: z.string(),
        data: z.object({
            accessToken: z.string(),
            refreshToken: z.string()
        }),
    }),
    requestSchema: z.object({
        refreshToken: z.string(),
    }),
    description: "Refresh token",
});

That’s one of the things I wanted to share! If you're interested, feel free to check out the repository or contribute to help improve this starter template, making it even more useful for everyone. 🚀