diff --git a/docs/examples.md b/docs/examples.md index 5fb0dc095..d505b9b1a 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -78,7 +78,7 @@ try {
-feature-fetch by builder.group +feature-fetch by builder.group ::: code-group @@ -257,26 +257,27 @@ TypeChecking in server environments can be tricky, as you’re often querying da ::: -## Hono with [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) +## Hono with [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) -Instead of manually typing each route with generics as in the [Hono example](#hono), [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) wraps around the [Hono router](https://hono.dev/docs/api/routing) to deliver full typesafety and enforce your OpenAPI-Schema with validators. +[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) provides full type-safety and runtime validation for your HonoAPI routes by wrapping a [Hono router](https://hono.dev/docs/api/routing): -::: tip Good To Know +::: tip Good to Know -While TypeScript types ensure compile-time safety, they don't enforce runtime schema validation. For runtime compliance, you need to integrate with validation libraries like Zod or Valibot. Although you must define the validation rules manually, they are type-safe to ensure these rules are correctly defined. +While TypeScript ensures compile-time type safety, runtime validation is equally important. `openapi-ts-router` integrates with Zod/Valibot to provide both: +- Types verify your code matches the OpenAPI spec during development +- Validators ensure incoming requests match the spec at runtime ::: ::: code-group ```ts [src/router.ts] -import { createHonoOpenApiRouter } from '@blgc/openapi-router'; import { Hono } from 'hono'; +import { createHonoOpenApiRouter } from 'openapi-ts-router'; import { zValidator } from 'validation-adapters/zod'; import * as z from 'zod'; - import { paths } from './gen/v1'; // OpenAPI-generated types -import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation +import { PetSchema } from './schemas'; // Custom reusable schema for validation export const router = new Hono(); export const openApiRouter = createHonoOpenApiRouter(router); @@ -302,41 +303,51 @@ openApiRouter.post('/pet', { return c.json({ name, photoUrls }); } }); + +// TypeScript will error if route/method doesn't exist in OpenAPI spec +// or if response doesn't match defined schema ``` ::: -[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore) +[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/hono/petstore) + +**Key benefits:** +- Full type safety for routes, methods, params, body and responses +- Runtime validation using Zod/Valibot +- Catches API spec mismatches at compile time +- Zero manual type definitions needed -## Express with [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) +## Express with [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) -[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) wraps around the [Express router](https://expressjs.com/en/5x/api.html#router) to deliver full typesafety and enforce your OpenAPI-Schema with validators. +[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) provides full type-safety and runtime validation for your Express API routes by wrapping a [Express router](https://expressjs.com/en/5x/api.html#router): -::: tip Good To Know +::: tip Good to Know -While TypeScript types ensure compile-time safety, they don't enforce runtime schema validation. For runtime compliance, you need to integrate with validation libraries like Zod or Valibot. Although you must define the validation rules manually, they are type-safe to ensure these rules are correctly defined. +While TypeScript ensures compile-time type safety, runtime validation is equally important. `openapi-ts-router` integrates with Zod/Valibot to provide both: +- Types verify your code matches the OpenAPI spec during development +- Validators ensure incoming requests match the spec at runtime ::: ::: code-group ```ts [src/router.ts] -import { createExpressOpenApiRouter } from '@blgc/openapi-router'; import { Router } from 'express'; -import * as v from 'valibot'; -import { vValidator } from 'validation-adapters/valibot'; - +import { createExpressOpenApiRouter } from 'openapi-ts-router'; +import * as z from 'zod'; +import { zValidator } from 'validation-adapters/zod'; import { paths } from './gen/v1'; // OpenAPI-generated types -import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation +import { PetSchema } from './schemas'; // Custom reusable schema for validation export const router: Router = Router(); export const openApiRouter = createExpressOpenApiRouter(router); // GET /pet/{petId} openApiRouter.get('/pet/{petId}', { - pathValidator: vValidator( - v.object({ - petId: v.number() // Validate that petId is a number + pathValidator: zValidator( + z.object({ + petId: z.number() // Validate that petId is a number }) ), handler: (req, res) => { @@ -347,17 +358,26 @@ openApiRouter.get('/pet/{petId}', { // POST /pet openApiRouter.post('/pet', { - bodyValidator: vValidator(PetSchema), // Validate request body using PetSchema + bodyValidator: zValidator(PetSchema), // Validate request body using PetSchema handler: (req, res) => { const { name, photoUrls } = req.body; // Access validated body data res.send({ name, photoUrls }); } }); + +// TypeScript will error if route/method doesn't exist in OpenAPI spec +// or if response doesn't match defined schema ``` ::: -[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore) +[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/express/petstore) + +**Key benefits:** +- Full type safety for routes, methods, params, body and responses +- Runtime validation using Zod/Valibot +- Catches API spec mismatches at compile time +- Zero manual type definitions needed ## Mock-Service-Worker (MSW) diff --git a/docs/ja/examples.md b/docs/ja/examples.md index 0e761d0e5..53d50269d 100644 --- a/docs/ja/examples.md +++ b/docs/ja/examples.md @@ -80,7 +80,7 @@ try {
-feature-fetch by builder.group +feature-fetch by builder.group ::: code-group @@ -262,9 +262,9 @@ export default app; ::: -## Hono と [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) +## Hono と [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) -[Honoの例](#hono) のように、各ルートをジェネリックで手動で型付けする代わりに、[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) は、[Hono router](https://hono.dev/docs/api/routing) をラップして完全な型安全性を提供し、バリデーターを使用してOpenAPIスキーマを強制します。 +[Honoの例](#hono) のように、各ルートをジェネリックで手動で型付けする代わりに、[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) は、[Hono router](https://hono.dev/docs/api/routing) をラップして完全な型安全性を提供し、バリデーターを使用してOpenAPIスキーマを強制します。 ::: tip 知っておくと良いこと @@ -275,7 +275,7 @@ TypeScriptの型はコンパイル時の安全性を保証しますが、実行 ::: code-group ```ts [src/router.ts] -import { createHonoOpenApiRouter } from "@blgc/openapi-router"; +import { createHonoOpenApiRouter } from "openapi-ts-router"; import { Hono } from "hono"; import { zValidator } from "validation-adapters/zod"; import * as z from "zod"; @@ -311,11 +311,11 @@ openApiRouter.post("/pet", { ::: -[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore) +[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/hono/petstore) -## Express と [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) +## Express と [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) -[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) は、[Express ルーター](https://expressjs.com/en/5x/api.html#router) をラップして、完全な型安全性を提供し、バリデーターを使用して OpenAPI スキーマを強制します。 +[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) は、[Express ルーター](https://expressjs.com/en/5x/api.html#router) をラップして、完全な型安全性を提供し、バリデーターを使用して OpenAPI スキーマを強制します。 ::: tip 知っておくと良いこと @@ -326,7 +326,7 @@ TypeScriptの型はコンパイル時の安全性を保証しますが、実行 ::: code-group ```ts [src/router.ts] -import { createExpressOpenApiRouter } from "@blgc/openapi-router"; +import { createExpressOpenApiRouter } from "openapi-ts-router"; import { Router } from "express"; import * as v from "valibot"; import { vValidator } from "validation-adapters/valibot"; @@ -362,7 +362,7 @@ openApiRouter.post("/pet", { ::: -[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore) +[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/express/petstore) ## Mock-Service-Worker (MSW)