Hono で作る REST API で 仕様と実装を同期しながらクライアントへスキーマ情報共有する方法の最適解をパターン別に検討してみた

- OpenAPIと実際のAPIレスポンスが乖離している
- OpenAPIと実際のバリデーション仕様が乖離しており400エラーになる
- OpenAPIを手書きでメンテナンスするのが大変、その結果陳腐化している
- APIを呼び出すクライアントを作るのが面倒

# スキーマの定義
UrlArea:
    type: object
    properties:
        actionType:
            type: string
            enum:
            - URL
        url:
            type: string
            format: uri
            example: https://example.com
    required:
        - actionType
        - url
CardArea:
    type: object
    properties:
        actionType:
            type: string
            enum:
            - CARD
        data:
            type: string
    required:
        - actionType
        - data

# oneOfで複数スキーマを割り当て
areas:
    type: array
    items:
    type: object
    oneOf:
        - $ref: "#/components/schemas/UrlArea"
        - $ref: "#/components/schemas/CardArea"

// 生成される型
export type UrlArea = {
  actionType: "URL";
  url: string;
};

export type CardArea = {
  actionType: "CARD";
  data: string;
};

// 型の絞り込みが容易になる
if (area.actionType === "URL") {
  console.log(area.url); // UrlAreaに絞り込まれる
}

# スキーマの定義
Area:
  type: object
  properties:
    actionType:
      type: string
      enum:
        - URL
        - CARD
    url:
      type: string
      format: uri
    data:
      type: string
  required:
    - actionType

// 生成される型
export type Area = {
  actionType: "URL" | "CARD";
  url?: string;
  data?: string;
};

// 型の絞り込みができない
if (area.actionType === "URL") {
  console.log(area.url); // エラー
}

root/
└── packages/
    ├── frontend/
    ├── server/
    └── shared/ # 型情報を定義するパッケージ

server/
├── package.json
└── src/
    ├── index.ts
    └── todos/
        ├── handlers.ts
        ├── index.ts
        ├── routes.ts
        └── storage.ts

shared/
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts
    ├── schemas.ts
    └── types.ts

import { z } from "@hono/zod-openapi";

export const TodoSchema1 = z.object({
	id: z.string().openapi({
		example: "10cb81aa-8807-46b8-809a-28aa7bede594",
	}),
	title: z.string().min(1, "タイトルは必須です").openapi({
		example: "人参を買う",
	}),
	completed: z.boolean().default(false).openapi({
		example: false,
	}),
	createdAt: z.string().datetime().openapi({
		example: "2021-01-01T00:00:00.000Z",
	}),
});

export const TodoSchema2 = z.object({
	id: z.string().openapi({
		example: "10cb81aa-8807-46b8-809a-28aa7bede594",
	}),
	title: z.string().min(1, "タイトルは必須です").openapi({
		example: "人参を買う",
	}),
	completed: z.boolean().default(false).openapi({
		example: false,
	}),
	createdAt: z.string().datetime().openapi({
		example: "2021-01-01T00:00:00.000Z",
	}),
	createdBy: z.string().openapi({
		example: "10cb81aa-8807-46b8-809a-28aa7bede594",
	}),
});

export const TodoSchema = z.union([TodoSchema1, TodoSchema2]);

// GET /todos - Response
export const GetTodosResponseSchema = z.array(TodoSchema);

// POST /todos - Request & Response
export const PostTodosRequestSchema = z.object({
	title: z.string().min(1, "Title is required").openapi({
		example: "ジャガイモを買う",
	}),
});

export const PostTodosResponseSchema = TodoSchema;

// PUT /todos/:id - Request & Response
export const PutTodosRequestSchema = z.object({
	title: z.string().min(1, "Title is required").optional().openapi({
		example: "ジャガイモを買う",
	}),
	completed: z.boolean().optional().openapi({
		example: true,
	}),
});

export const PutTodosResponseSchema = TodoSchema;

// DELETE /todos/:id - Request params
export const DeleteTodosParamsSchema = z.object({
	id: z.string(),
});

// Common params schema
export const TodoParamsSchema = z.object({
	id: z.string(),
});

import { createRoute } from "@hono/zod-openapi";
import {
	GetTodosResponseSchema,
	PostTodosRequestSchema,
	PostTodosResponseSchema,
	PutTodosRequestSchema,
	PutTodosResponseSchema,
	TodoParamsSchema,
} from "shared";

export const getTodosRoute = createRoute({
	method: "get",
	path: "/",
	responses: {
		200: {
			content: {
				"application/json": {
					schema: GetTodosResponseSchema,
				},
			},
			description: "List of todos",
		},
	},
});

export const createTodoRoute = createRoute({
	method: "post",
	path: "/",
	request: {
		body: {
			content: {
				"application/json": {
					schema: PostTodosRequestSchema,
				},
			},
		},
	},
	responses: {
		201: {
			content: {
				"application/json": {
					schema: PostTodosResponseSchema,
				},
			},
			description: "Created todo",
		},
		400: {
			description: "Invalid request body",
		},
	},
});

export const updateTodoRoute = createRoute({
	method: "put",
	path: "/{id}",
	request: {
		params: TodoParamsSchema,
		body: {
			content: {
				"application/json": {
					schema: PutTodosRequestSchema,
				},
			},
		},
	},
	responses: {
		200: {
			content: {
				"application/json": {
					schema: PutTodosResponseSchema,
				},
			},
			description: "Updated todo",
		},
		404: {
			description: "Todo not found",
		},
		400: {
			description: "Invalid request body",
		},
	},
});

export const deleteTodoRoute = createRoute({
	method: "delete",
	path: "/{id}",
	request: {
		params: TodoParamsSchema,
	},
	responses: {
		204: {
			description: "Todo deleted successfully",
		},
		404: {
			description: "Todo not found",
		},
	},
});

import type { RouteHandler } from "@hono/zod-openapi";
import type {
	createTodoRoute,
	deleteTodoRoute,
	getTodosRoute,
	updateTodoRoute,
} from "./routes";
import { todoStorage } from "./storage";

export const getTodos: RouteHandler<typeof getTodosRoute> = (c) => {
	const todos = todoStorage.getAll();
	return c.json(todos, 200);
};

export const createTodo: RouteHandler<typeof createTodoRoute> = (c) => {
	const body = c.req.valid("json");
	const id = crypto.randomUUID();
	const todo = {
		id,
		title: body.title,
		completed: false,
		createdAt: new Date().toISOString(),
	};

	const created = todoStorage.create(todo);
	return c.json(created, 201);
};

export const updateTodo: RouteHandler<typeof updateTodoRoute> = (c) => {
	const { id } = c.req.valid("param");
	const body = c.req.valid("json");

	const updated = todoStorage.update(id, body);

	if (!updated) {
		return c.json({ error: "Todo not found" }, 404);
	}

	return c.json(updated, 200);
};

export const deleteTodo: RouteHandler<typeof deleteTodoRoute> = (c) => {
	const { id } = c.req.valid("param");

	const deleted = todoStorage.delete(id);

	if (!deleted) {
		return c.json({ error: "Todo not found" }, 404);
	}

	return c.body(null, 204);
};

import { OpenAPIHono } from "@hono/zod-openapi";
import { createTodo, deleteTodo, getTodos, updateTodo } from "./handlers";
import {
	createTodoRoute,
	deleteTodoRoute,
	getTodosRoute,
	updateTodoRoute,
} from "./routes";

export const todosRouter = new OpenAPIHono();

todosRouter.openapi(getTodosRoute, getTodos);
todosRouter.openapi(createTodoRoute, createTodo);
todosRouter.openapi(updateTodoRoute, updateTodo);
todosRouter.openapi(deleteTodoRoute, deleteTodo);

import { serve } from "@hono/node-server";
import { swaggerUI } from "@hono/swagger-ui";
import { OpenAPIHono } from "@hono/zod-openapi";
import { Scalar } from "@scalar/hono-api-reference";
import { todosRouter } from "./todos";

export const app = new OpenAPIHono();

app.route("/todos", todosRouter);

app.doc("/doc", {
	openapi: "3.0.0",
	info: {
		version: "1.0.0",
		title: "TODO API with Hono + Zod OpenAPI",
		description:
			"A simple TODO API demonstrating Hono with Zod OpenAPI integration",
	},
});

// Swagger UI
app.get("/ui", swaggerUI({ url: "/doc" }));

// Scalar
app.get("/scalar", Scalar({ url: "/doc" }));

const port = 3000;

serve({
	fetch: app.fetch,
	port,
});

console.log(`Server is running on port ${port}`);

export const getTodos: RouteHandler<typeof getTodosRoute> = (c) => {
	const todos = todoStorage.getAll();

	// レスポンスバリデーション
	const result = GetTodosResponseSchema.safeParse(todos);
	if (!result.success) {
		console.error("Response validation error:", result.error);
		throw new Error("レスポンスデータのバリデーションに失敗しました");
	}

	return c.json(result.data, 200);
};

import { hc } from "hono/client";
import type { AppType } from "server";
import type { Todo } from "shared";
import type { TodoApiClient } from "./types";
import { ApiError } from "./types";

export class HonoRpcClient implements TodoApiClient {
	private client: ReturnType<typeof hc<AppType>>;

	constructor(baseUrl = "/api") {
		this.client = hc<AppType>(baseUrl);
	}

	async getTodos(): Promise<Todo[]> {
		try {
			const response = await this.client.todos.$get();
			if (!response.ok) {
				throw new ApiError(
					`Failed to fetch todos: ${response.status}`,
					response.status
				);
			}
			return await response.json();
		} catch (error) {
			if (error instanceof ApiError) throw error;
			throw new ApiError("Network error", 0, error);
		}
	}

	async createTodo(title: string): Promise<Todo> {
		try {
			const response = await this.client.todos.$post({
				json: { title },
			});
			if (!response.ok) {
				throw new ApiError(
					`Failed to create todo: ${response.status}`,
					response.status
				);
			}
			return await response.json();
		} catch (error) {
			if (error instanceof ApiError) throw error;
			throw new ApiError("Network error", 0, error);
		}
	}

	async updateTodo(
		id: string,
		data: { title?: string; completed?: boolean }
	): Promise<Todo> {
		try {
			const response = await this.client.todos[":id"].$put({
				param: { id },
				json: data,
			});
			if (!response.ok) {
				throw new ApiError(
					`Failed to update todo: ${response.status}`,
					response.status
				);
			}
			return await response.json();
		} catch (error) {
			if (error instanceof ApiError) throw error;
			throw new ApiError("Network error", 0, error);
		}
	}

	async deleteTodo(id: string): Promise<void> {
		try {
			const response = await this.client.todos[":id"].$delete({
				param: { id },
			});
			if (!response.ok) {
				throw new ApiError(
					`Failed to delete todo: ${response.status}`,
					response.status
				);
			}
		} catch (error) {
			if (error instanceof ApiError) throw error;
			throw new ApiError("Network error", 0, error);
		}
	}
}

npx openapi-typescript https://localhost:3000/doc -o ./shared/src/generated/types.ts

import createClient from "openapi-fetch";
import type { Todo } from "shared";
import type { paths } from "../generated/api-types";
import type { TodoApiClient } from "./types";
import { ApiError } from "./types";

export class OpenApiFetchClient implements TodoApiClient {
	private client: ReturnType<typeof createClient<paths>>;

	constructor(baseUrl: string = "/api") {
		this.client = createClient<paths>({ baseUrl });
	}

	async getTodos(): Promise<Todo[]> {
		try {
			const { data, error } = await this.client.GET("/todos");

			if (error) {
				throw new ApiError(`Failed to get todos: ${error}`, 500, error);
			}

			return data || [];
		} catch (error) {
			if (error instanceof ApiError) {
				throw error;
			}
			throw new ApiError("Failed to get todos", 500, error);
		}
	}

	async createTodo(title: string): Promise<Todo> {
		try {
			const { data, error } = await this.client.POST("/todos", {
				body: { title },
			});

			if (error) {
				throw new ApiError(`Failed to create todo: ${error}`, 400, error);
			}

			if (!data) {
				throw new ApiError("No data returned from create todo", 500);
			}

			return data;
		} catch (error) {
			if (error instanceof ApiError) {
				throw error;
			}
			throw new ApiError("Failed to create todo", 500, error);
		}
	}

	async updateTodo(
		id: string,
		updateData: { title?: string; completed?: boolean }
	): Promise<Todo> {
		try {
			const { data, error } = await this.client.PUT("/todos/{id}", {
				params: { path: { id } },
				body: updateData,
			});

			if (error) {
				throw new ApiError(`Failed to update todo: ${error}`, 400, error);
			}

			if (!data) {
				throw new ApiError("No data returned from update todo", 500);
			}

			return data;
		} catch (error) {
			if (error instanceof ApiError) {
				throw error;
			}
			throw new ApiError("Failed to update todo", 500, error);
		}
	}

	async deleteTodo(id: string): Promise<void> {
		try {
			const { error } = await this.client.DELETE("/todos/{id}", {
				params: { path: { id } },
			});

			if (error) {
				throw new ApiError(`Failed to delete todo: ${error}`, 400, error);
			}
		} catch (error) {
			if (error instanceof ApiError) {
				throw error;
			}
			throw new ApiError("Failed to delete todo", 500, error);
		}
	}
}

import type { z } from "zod";
import type {
	DeleteTodosParamsSchema,
	GetTodosResponseSchema,
	PostTodosRequestSchema,
	PostTodosResponseSchema,
	PutTodosRequestSchema,
	PutTodosResponseSchema,
	TodoParamsSchema,
	TodoSchema,
} from "./schemas";

export type Todo = z.infer<typeof TodoSchema>;

// API Request/Response types
export type GetTodosResponse = z.infer<typeof GetTodosResponseSchema>;

export type PostTodosRequest = z.infer<typeof PostTodosRequestSchema>;
export type PostTodosResponse = z.infer<typeof PostTodosResponseSchema>;

export type PutTodosRequest = z.infer<typeof PutTodosRequestSchema>;
export type PutTodosResponse = z.infer<typeof PutTodosResponseSchema>;

export type DeleteTodosParams = z.infer<typeof DeleteTodosParamsSchema>;
export type TodoParams = z.infer<typeof TodoParamsSchema>;