Skip to content

Commit

Permalink
Updated example docs (because of rename from @blgc/openapi-router to …
Browse files Browse the repository at this point in the history 
…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]>
  • Loading branch information
@bennobuilder
bennobuilder and bennobuilder authored Jan 3, 2025
1 parent 8c3b36c commit dcd7a86
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 32 deletions.
66 changes: 43 additions & 23 deletions docs/examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ try {
</details>

<details>
<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>
<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>

::: code-group

Expand Down Expand Up @@ -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<paths>(router);
Expand All @@ -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<paths>(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) => {
Expand All @@ -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)

Expand Down
18 changes: 9 additions & 9 deletions docs/ja/examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ try {
</details>

<details>
<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>
<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>

::: code-group

Expand Down Expand Up @@ -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 知っておくと良いこと

Expand All @@ -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";
Expand Down Expand Up @@ -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 知っておくと良いこと

Expand All @@ -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";
Expand Down Expand Up @@ -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)

Expand Down

0 comments on commit dcd7a86

Please sign in to comment.