Refactor to separate itty-router from openapi logic - #151

This refactors the OpenAPI logic and adds support for latest versions of itty-router and possibly other router (like hono)

The new version will require users to instantiate their own itty-router router like:

import { fromIttyRouter } from '@cloudflare/itty-router-openapi'
import { AutoRouter } from 'itty-router'
import { ToDoGet } from './todo'

const openapiRouter = fromIttyRouter(AutoRouter())
openapiRouter.get('/todo', ToDoGet)

export default openapiRouter

Breaking changes:

• removed OpenAPIRouter() method
• removed aiPlugin option
• removed skipValidation option (see new validation method bellow)
• itty-router is no longer a dependency and users must manually add it to their project
• validated data is no longer send in the last argument of the handler function (see new validation method bellow)
• Endpoint's schema is no longer a static variable
• Endpoint's schema.parameters was renamed to schema.request to follow zod-to-openapi structure
• Endpoint Path parameters are now called params to match the validated Data object name
• Endpoint's schema.requestBody was renamed to schema.request.body to follow zod-to-openapi structure
• Validation no longer occurs before the endpoint's handle function is called, developers must manually call the getValidatedData to execute the data validation step
  • Tip: you can wrap this function call with try {} catch (e) {} to handle input errors, otherwise this library will return the errors in a Json response with http 400

Additions:

• new await this.getValidatedData<typeof this.schema>() method to retrieve all validated data, when sending <typeof this.schema> in the generic the returned value will have full typescript inference based on the schema
• automatically coerce all headers, query and params inputs based on specified zod type
• new fromIttyRouter() instantiate method
• new fromHono() instantiate method

Migration guide:

• install latest version
• install latest itty-router version (npm install itty-router@latest --save)
• replace your current router instance
  • from: const router = OpenAPIRouter({...})
  • to: const router = fromIttyRouter(Router(), {...})
• remove the new from all "legacy type" call from new Str(...) into Str(...)
• remove the data argument from your endpoint's handle function
  • from: async handle(request: Request, env: Env, ctx: Context, data: any) {...}
  • to: async handle(request: Request, env: Env, ctx: Context) {...}
• add this variable to the first line of your endpoint handle function const data = await this.getValidatedData<typeof this.schema>()
• remove the static keyword from the endpoints schema property from:static schema to: schema
• move query parameters from schema.parameters.query into schema.request.query
• move path parameters from schema.parameters.path into schema.request.params
• move headers parameters from schema.parameters.headers into schema.request.headers
• wrap your query, headers and params into a zod object z.object({...})
• move you schema.requestBody into schema.request.body: contentJson(z.object({...params.newModel}))

Minimal Hono example

import { extendZodWithOpenApi, fromHono, OpenAPIRoute } from '@cloudflare/itty-router-openapi'
import { Hono } from 'hono'
import { z } from 'zod'

extendZodWithOpenApi(z)

export class GetPageNumber extends OpenAPIRoute {
  schema = {
    request: {
      params: z.object({
        id: z.string().min(2).max(10),
      }),
      query: z.object({
        page: z.number().int().min(0).max(20),
      }),
    },
  }

  async handle(c) {
    const data = await this.getValidatedData<typeof this.schema>()

    return c.json({
      id: data.params.id,
      page: data.query.page,
    })
  }
}


const app = new Hono()
const openapi = fromHono(app)

openapi.get('/entry/:id', GetPageNumber)
export default app