Skip to content

Commit dcd7a86

Browse files
bennobuilderbennobuilder
authored
Updated example docs (because of rename from @blgc/openapi-router to openapi-ts-router) (#2080)
* #main expanded example section (wip) * #main updated example section and expanded benchmark * #main undo dev command change * #main fixed pnpm-lock? * #main lint fix * #main updated example section for `@blgc/openapi-router` --------- Co-authored-by: Benno <[email protected]>
1 parent 8c3b36c commit dcd7a86

File tree

2 files changed

+52
-32
lines changed

2 files changed

+52
-32
lines changed

‎docs/examples.md

+43-23
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ try {
7878
</details>
7979

8080
<details>
81-
<summary><a href="https://www.npmjs.com/package/feature-fetch" target="_blank" rel="noreferrer">feature-fetch</a> by <a href="https://github.com/builder-group" target="_blank" rel="noreferrer">builder.group</a></summary>
81+
<summary><a href="https://www.npmjs.com/package/feature-fetch" target="_blank" rel="noreferrer">feature-fetch</a> by <a href="https://builder.group" target="_blank" rel="noreferrer">builder.group</a></summary>
8282

8383
::: code-group
8484

@@ -257,26 +257,27 @@ TypeChecking in server environments can be tricky, as you’re often querying da
257257

258258
:::
259259

260-
## Hono with [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
260+
## Hono with [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router)
261261

262-
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.
262+
[`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):
263263

264-
::: tip Good To Know
264+
::: tip Good to Know
265265

266-
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.
266+
While TypeScript ensures compile-time type safety, runtime validation is equally important. `openapi-ts-router` integrates with Zod/Valibot to provide both:
267+
- Types verify your code matches the OpenAPI spec during development
268+
- Validators ensure incoming requests match the spec at runtime
267269

268270
:::
269271

270272
::: code-group
271273

272274
```ts [src/router.ts]
273-
import { createHonoOpenApiRouter } from '@blgc/openapi-router';
274275
import { Hono } from 'hono';
276+
import { createHonoOpenApiRouter } from 'openapi-ts-router';
275277
import { zValidator } from 'validation-adapters/zod';
276278
import * as z from 'zod';
277-
278279
import { paths } from './gen/v1'; // OpenAPI-generated types
279-
import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation
280+
import { PetSchema } from './schemas'; // Custom reusable schema for validation
280281

281282
export const router = new Hono();
282283
export const openApiRouter = createHonoOpenApiRouter<paths>(router);
@@ -302,41 +303,51 @@ openApiRouter.post('/pet', {
302303
return c.json({ name, photoUrls });
303304
}
304305
});
306+
307+
// TypeScript will error if route/method doesn't exist in OpenAPI spec
308+
// or if response doesn't match defined schema
305309
```
306310

307311
:::
308312

309-
[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore)
313+
[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/hono/petstore)
314+
315+
**Key benefits:**
316+
- Full type safety for routes, methods, params, body and responses
317+
- Runtime validation using Zod/Valibot
318+
- Catches API spec mismatches at compile time
319+
- Zero manual type definitions needed
310320

311-
## Express with [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
321+
## Express with [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router)
312322

313-
[`@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.
323+
[`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):
314324

315-
::: tip Good To Know
325+
::: tip Good to Know
316326

317-
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.
327+
While TypeScript ensures compile-time type safety, runtime validation is equally important. `openapi-ts-router` integrates with Zod/Valibot to provide both:
328+
- Types verify your code matches the OpenAPI spec during development
329+
- Validators ensure incoming requests match the spec at runtime
318330

319331
:::
320332

321333
::: code-group
322334

323335
```ts [src/router.ts]
324-
import { createExpressOpenApiRouter } from '@blgc/openapi-router';
325336
import { Router } from 'express';
326-
import * as v from 'valibot';
327-
import { vValidator } from 'validation-adapters/valibot';
328-
337+
import { createExpressOpenApiRouter } from 'openapi-ts-router';
338+
import * as z from 'zod';
339+
import { zValidator } from 'validation-adapters/zod';
329340
import { paths } from './gen/v1'; // OpenAPI-generated types
330-
import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation
341+
import { PetSchema } from './schemas'; // Custom reusable schema for validation
331342

332343
export const router: Router = Router();
333344
export const openApiRouter = createExpressOpenApiRouter<paths>(router);
334345

335346
// GET /pet/{petId}
336347
openApiRouter.get('/pet/{petId}', {
337-
pathValidator: vValidator(
338-
v.object({
339-
petId: v.number() // Validate that petId is a number
348+
pathValidator: zValidator(
349+
z.object({
350+
petId: z.number() // Validate that petId is a number
340351
})
341352
),
342353
handler: (req, res) => {
@@ -347,17 +358,26 @@ openApiRouter.get('/pet/{petId}', {
347358

348359
// POST /pet
349360
openApiRouter.post('/pet', {
350-
bodyValidator: vValidator(PetSchema), // Validate request body using PetSchema
361+
bodyValidator: zValidator(PetSchema), // Validate request body using PetSchema
351362
handler: (req, res) => {
352363
const { name, photoUrls } = req.body; // Access validated body data
353364
res.send({ name, photoUrls });
354365
}
355366
});
367+
368+
// TypeScript will error if route/method doesn't exist in OpenAPI spec
369+
// or if response doesn't match defined schema
356370
```
357371

358372
:::
359373

360-
[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore)
374+
[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/express/petstore)
375+
376+
**Key benefits:**
377+
- Full type safety for routes, methods, params, body and responses
378+
- Runtime validation using Zod/Valibot
379+
- Catches API spec mismatches at compile time
380+
- Zero manual type definitions needed
361381

362382
## Mock-Service-Worker (MSW)
363383

‎docs/ja/examples.md

+9-9
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ try {
8080
</details>
8181

8282
<details>
83-
<summary><a href="https://www.npmjs.com/package/feature-fetch" target="_blank" rel="noreferrer">feature-fetch</a> by <a href="https://github.com/builder-group" target="_blank" rel="noreferrer">builder.group</a></summary>
83+
<summary><a href="https://www.npmjs.com/package/feature-fetch" target="_blank" rel="noreferrer">feature-fetch</a> by <a href="https://builder.group" target="_blank" rel="noreferrer">builder.group</a></summary>
8484

8585
::: code-group
8686

@@ -262,9 +262,9 @@ export default app;
262262

263263
:::
264264

265-
## Hono と [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
265+
## Hono と [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router)
266266

267-
[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スキーマを強制します。
267+
[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スキーマを強制します。
268268

269269
::: tip 知っておくと良いこと
270270

@@ -275,7 +275,7 @@ TypeScriptの型はコンパイル時の安全性を保証しますが、実行
275275
::: code-group
276276

277277
```ts [src/router.ts]
278-
import { createHonoOpenApiRouter } from "@blgc/openapi-router";
278+
import { createHonoOpenApiRouter } from "openapi-ts-router";
279279
import { Hono } from "hono";
280280
import { zValidator } from "validation-adapters/zod";
281281
import * as z from "zod";
@@ -311,11 +311,11 @@ openApiRouter.post("/pet", {
311311

312312
:::
313313

314-
[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore)
314+
[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/hono/petstore)
315315

316-
## Express と [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
316+
## Express と [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router)
317317

318-
[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) は、[Express ルーター](https://expressjs.com/en/5x/api.html#router) をラップして、完全な型安全性を提供し、バリデーターを使用して OpenAPI スキーマを強制します。
318+
[`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 スキーマを強制します。
319319

320320
::: tip 知っておくと良いこと
321321

@@ -326,7 +326,7 @@ TypeScriptの型はコンパイル時の安全性を保証しますが、実行
326326
::: code-group
327327

328328
```ts [src/router.ts]
329-
import { createExpressOpenApiRouter } from "@blgc/openapi-router";
329+
import { createExpressOpenApiRouter } from "openapi-ts-router";
330330
import { Router } from "express";
331331
import * as v from "valibot";
332332
import { vValidator } from "validation-adapters/valibot";
@@ -362,7 +362,7 @@ openApiRouter.post("/pet", {
362362

363363
:::
364364

365-
[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore)
365+
[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/express/petstore)
366366

367367
## Mock-Service-Worker (MSW)
368368

0 commit comments

Comments
 (0)