\n OpenAPI 3 and 3.1 schema generator and validator for Cloudflare Workers\n
\n\n---\n\n**Documentation**: https://cloudflare.github.io/itty-router-openapi/\n\n**Source Code**: https://github.com/cloudflare/itty-router-openapi/\n\n---\n\n[itty-router-openapi](https://github.com/cloudflare/itty-router-openapi) is a library that\nextends [itty-router](https://github.com/kwhitley/itty-router), a powerful and lightweight routing system for Cloudflare\nWorkers, already familiar to many developers, and adds an easy-to-use and\ncompact [OpenAPI 3 and 3.1](https://swagger.io/specification/) schema generator and\nvalidator.\n\nitty-route-openapi can also have class-based routes, allowing the developer to quickly build on top of and extend other\nendpoints while reusing code.\n\nThe key features are:\n\n- OpenAPI 3 and 3.1 schema generator\n- Parameter type hint and type check in typescript\n- [Query](https://cloudflare.github.io/itty-router-openapi/user-guide/query-parameters/),\n [Path](https://cloudflare.github.io/itty-router-openapi/user-guide/path-parameters/),\n [Request Body](https://cloudflare.github.io/itty-router-openapi/user-guide/request-body/) and\n [Header](https://cloudflare.github.io/itty-router-openapi/user-guide/header-parameters/) validator\n- Fully written in typescript\n- Class-based endpoints\n- Out of the box [OpenAI plugin support](https://cloudflare.github.io/itty-router-openapi/advanced-user-guide/openai-plugin/)\n- [Drop-in replacement](https://cloudflare.github.io/itty-router-openapi/migrating-from-itty-router/) for existing itty-router applications\n\nA template repository is available\nat [cloudflare/workers-sdk](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-openapi),\nwith a live demo [here](https://worker-openapi-example.radar.cloudflare.com/docs).\n\n## Why create another router library for workers?\n\nThis framework built on top of [itty-router](https://github.com/kwhitley/itty-router) and extends some of its\ncore features, such as adding class-based endpoints. It also provides a simple and iterative path for migrating from old\napplications based on `itty-router`.\n\nBuilding APIs and maintaining good documentation on the parameters and fields of your API hard. However, there is an\nopen standard that makes this documentation process much more effortless, called [OpenAPI](https://www.openapis.org/).\n\nOpenAPI \"defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to\ndiscover and understand the capabilities of the service without access to source code, documentation, or through network\ntraffic inspection.\" This allows other machines to reliably parse those definitions and use the remote APIs easily,\nwithout additional implementation logic.\n\nSome of the top requirements for Radar 2.0 were having better API documentation, improving the deployment lifecycle with\nend-to-end testing, and making it publicly available to Cloudflare customers. OpenAPI support quickly jumped out as the\nobvious choice to help us on all these fronts.\n\nHowever, we struggled to find an existing OpenAPI framework that checked all our boxes:\n\n- Easy integration with Cloudflare Workers\n- Input validation for endpoints parameters\n- Actual code-based schema generation (not just generated from comments or manually)\n\nSince we couldn't find anything that suited us, as many engineers do, we opted for the second-best alternative: building\nour own and open-source it.\n\n## Quick setup\n\nGet started fast using the `create-cloudflare` command line, just run this command to setup an initial project with\nsome example routes:\n\n\n\n```bash\nnpm create cloudflare@latest hello-world -- --type openapi\n\n---> 100%\n```\n\nThen to start the local server just run\n\n```bash\ncd hello-world\nwrangler dev\n```\n\n## Installation\n\n\n\n```bash\nnpm i @cloudflare/itty-router-openapi --save\n\n---> 100%\n```\n\n## Example\n\nLet's create our first class-based endpoint called TaskFetch in src/tasks.ts now.\n\nMake sure that ‘Task' is global, otherwise you must redefine `responses.schema.task` with every endpoint.\n\nWhen defining the schema, you can interchangeably use native typescript types or use the included types to set required\nflags, descriptions, and other fields.\n\n```ts\nimport {\n OpenAPIRoute,\n Path,\n Str,\n DateOnly,\n DataOf,\n} from '@cloudflare/itty-router-openapi'\n\nconst Task = {\n name: new Str({ example: 'lorem' }),\n slug: String,\n description: new Str({ required: false }),\n completed: Boolean,\n due_date: new DateOnly(),\n}\n\nexport class TaskFetch extends OpenAPIRoute {\n static schema = {\n tags: ['Tasks'],\n summary: 'Get a single Task by slug',\n parameters: {\n taskSlug: Path(Str, {\n description: 'Task slug',\n }),\n },\n responses: {\n '200': {\n description: 'Task fetched successfully',\n schema: {\n metaData: {},\n task: Task,\n },\n },\n },\n }\n\n async handle(\n request: Request,\n env: any,\n context: any,\n data: DataOf