diff --git a/README.md b/README.md index 3baca9b..03f3edb 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,12 @@ To see real world usage of these utilities, checkout the [hono-open-api-starter - [Example Usage](#example-usage-10) - [stoker/openapi/schemas/id-uuid-params](#stokeropenapischemasid-uuid-params) - [Example Usage](#example-usage-11) - - [stoker/openapi/schemas/create-message-object](#stokeropenapischemascreate-message-object) + - [stoker/openapi/schemas/get-params-schema](#stokeropenapischemasget-params-schema) - [Example Usage](#example-usage-12) - - [stoker/openapi/schemas/create-error-schema](#stokeropenapischemascreate-error-schema) + - [stoker/openapi/schemas/create-message-object](#stokeropenapischemascreate-message-object) - [Example Usage](#example-usage-13) + - [stoker/openapi/schemas/create-error-schema](#stokeropenapischemascreate-error-schema) + - [Example Usage](#example-usage-14) - [Credits](#credits) ## Utilities @@ -467,6 +469,54 @@ app.openapi( export default app; ``` +#### stoker/openapi/schemas/get-params-schema + +Validate a custom named path param using Zod string validators by calling the function `getParamsSchema({ name, validator })`. + +Name defaults to `id`. +Validator defaults to `uuid` and supports type `"uuid" | "nanoid" | "cuid" | "cuid2" | "ulid"`. + +##### Example Usage + +```ts +import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi"; +import * as HttpStatusCodes from "stoker/http-status-codes"; +import jsonContent from "stoker/openapi/helpers/json-content"; +import getParamsSchema from "stoker/openapi/schemas/get-params-schema"; + +const app = new OpenAPIHono(); + +app.openapi( + createRoute({ + method: "get", + path: "/users/{userId}", + request: { + params: getParamsSchema({ + name: "userId", + validator: "nanoid", + }), + }, + responses: { + [HttpStatusCodes.OK]: jsonContent( + z.object({ + userId: z.nanoid(), + }), + "Retrieve the user", + ), + }, + }), + (c) => { + // userId is a valid nanoid + const { userId } = c.req.valid("param"); + return c.json({ + userId, + }, HttpStatusCodes.OK); + }, +); + +export default app; +``` + #### stoker/openapi/schemas/create-message-object Create an object schema with a message string property. Useful for error messages. diff --git a/package.json b/package.json index 9b16a5a..bf4097b 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "stoker", "type": "module", - "version": "1.2.7", + "version": "1.3.0", "packageManager": "pnpm@9.9.0", "description": "Utilities for hono and @hono/zod-openapi", "author": "w3cj ", @@ -200,6 +200,16 @@ "default": "./dist/cjs/openapi/schemas/slug-params.js" } }, + "./openapi/schemas/get-params-schema": { + "import": { + "types": "./dist/esm/openapi/schemas/get-params-schema.d.ts", + "default": "./dist/esm/openapi/schemas/get-params-schema.js" + }, + "require": { + "types": "./dist/cjs/openapi/schemas/get-params-schema.d.ts", + "default": "./dist/cjs/openapi/schemas/get-params-schema.js" + } + }, "./openapi/schemas/create-message-object": { "import": { "types": "./dist/esm/openapi/schemas/create-message-object.d.ts", @@ -280,6 +290,9 @@ "openapi/schemas/slug-params": [ "./dist/esm/openapi/schemas/slug-params.d.ts" ], + "openapi/schemas/get-params-schema": [ + "./dist/esm/openapi/schemas/get-params-schema.d.ts" + ], "openapi/schemas/create-message-object": [ "./dist/esm/openapi/schemas/create-message-object.d.ts" ], diff --git a/src/openapi/schemas/get-params-schema.ts b/src/openapi/schemas/get-params-schema.ts new file mode 100644 index 0000000..05f9c10 --- /dev/null +++ b/src/openapi/schemas/get-params-schema.ts @@ -0,0 +1,34 @@ +import { z } from "@hono/zod-openapi"; + +type Validator = "uuid" | "nanoid" | "cuid" | "cuid2" | "ulid"; + +export interface ParamsSchema { + name?: string; + validator?: Validator | undefined; +} + +const examples: Record = { + uuid: "4651e634-a530-4484-9b09-9616a28f35e3", + nanoid: "V1StGXR8_Z5jdHi6B-myT", + cuid: "cjld2cjxh0000qzrmn831i7rn", + cuid2: "tz4a98xxat96iws9zmbrgj3a", + ulid: "01ARZ3NDEKTSV4RRFFQ69G5FAV", +}; + +const getParamsSchema = ({ + name = "id", + validator = "uuid", +}: ParamsSchema) => { + return z.object({ + [name]: z.string()[validator]().openapi({ + param: { + name, + in: "path", + }, + required: [name], + example: examples[validator], + }), + }); +}; + +export default getParamsSchema;