Merge pull request #1286 from hey-api/feat/fastify-plugin

feat: add fastify plugin

.changeset/fast-dolls-pull.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix: export a map of error and response types by status code

.changeset/gorgeous-cups-search.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+feat: add `fastify` plugin

.changeset/honest-rings-obey.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix: deprecate types.tree option

docs/.vitepress/config/en.ts

@@ -47,6 +47,10 @@ export default defineConfig({
       },
       {
         items: [
+          {
+            link: '/openapi-ts/fastify',
+            text: 'Fastify',
+          },
           {
             link: '/openapi-ts/tanstack-query',
             text: 'TanStack Query',

docs/embed.ts

@@ -25,6 +25,13 @@ export const embedProject = (projectId: string) => async (event: Event) => {
           'openapi-ts.config.ts,src/client/schemas.gen.ts,src/client/services.gen.ts,src/client/types.gen.ts,src/App.tsx',
         view: 'editor',
       });
+    case 'hey-api-client-fetch-plugin-fastify-example':
+      return await sdk.embedProjectId(container, projectId, {
+        height: 700,
+        openFile:
+          'openapi-ts.config.ts,src/client/fastify.gen.ts,src/client/types.gen.ts,src/server.ts',
+        view: 'editor',
+      });
     case 'hey-api-client-fetch-plugin-tanstack-react-query-example':
       return await sdk.embedProjectId(container, projectId, {
         height: 700,

docs/openapi-ts/configuration.md

@@ -236,7 +236,7 @@ npx @hey-api/openapi-ts -i path/to/openapi.json -o src/client -c @hey-api/client
 
 The experimental parser produces a cleaner output while being faster than the legacy parser. It also supports features such as [Filters](#filters) and more will be added in the future.
 
-The legacy parser will remain enabled for the [legacy clients](/openapi-ts/clients/legacy) regardless of the `experimentalParser` flag value. However, it's unlikely to receive any further updates.
+The legacy parser will be used with the [legacy clients](/openapi-ts/clients/legacy) regardless of the `experimentalParser` flag value. However, it's unlikely to receive any further updates.
 
 ## Config API
 

docs/openapi-ts/fastify.md

@@ -0,0 +1,75 @@
+---
+title: Fastify
+description: Fastify plugin for Hey API. Compatible with all our features.
+---
+
+# Fastify
+
+::: warning
+Fastify plugin is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
+:::
+
+[Fastify](https://fastify.dev/) is a fast and low overhead web framework for Node.js.
+
+<button class="buttonLink" @click="(event) => embedProject('hey-api-client-fetch-plugin-fastify-example')(event)">
+Live demo
+</button>
+
+## Features
+
+- seamless integration with `@hey-api/openapi-ts` ecosystem
+- type-safe route handlers
+- minimal learning curve thanks to extending the underlying technology
+
+## Installation
+
+::: warning
+Fastify plugin works only with the [experimental parser](/openapi-ts/configuration#parser) which is currently an opt-in feature.
+:::
+
+Ensure you have already [configured](/openapi-ts/get-started) `@hey-api/openapi-ts`. Update your configuration to use the Fastify plugin.
+
+```js
+export default {
+  client: '@hey-api/client-fetch',
+  experimentalParser: true, // [!code ++]
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    'fastify', // [!code ++]
+  ],
+};
+```
+
+You can now generate Fastify artifacts. 🎉
+
+## Output
+
+The Fastify plugin will generate the following artifacts, depending on the input specification.
+
+## Route Handlers
+
+Route handlers are generated from all endpoints. The generated interface follows the naming convention of services.
+
+```ts
+const fastify = Fastify();
+const serviceHandlers: RouteHandlers = {
+  createPets(request, reply) {
+    reply.code(201).send();
+  },
+  listPets(request, reply) {
+    reply.code(200).send([]);
+  },
+  showPetById(request, reply) {
+    reply.code(200).send({
+      id: Number(request.params.petId),
+      name: 'Kitty',
+    });
+  },
+};
+fastify.register(glue, { serviceHandlers });
+```
+
+<!--@include: ../examples.md-->
+<!--@include: ../sponsorship.md-->

docs/openapi-ts/migrating.md

@@ -50,6 +50,12 @@ This config option is deprecated and will be removed in favor of [clients](./cli
 
 This config option is deprecated and will be removed.
 
+## v0.56.0
+
+### Deprecated `tree` in `@hey-api/types`
+
+This config option is deprecated and will be removed when the experimental parser becomes the default.
+
 ## v0.55.0
 
 This release adds the ability to filter your OpenAPI specification before it's processed. This feature will be useful if you are working with a large specification and are interested in generating output only from a small subset.

docs/openapi-ts/output.md

@@ -28,7 +28,7 @@ my-app/
 └── package.json
 ```
 
-Each file is an artifact generated by a plugin. This is the default output, we will cover customizing it on this page.
+Each file is an artifact generated by a Hey API plugin. This is the default output, we will cover customizing it on this page. These files also form the base for third-party plugins.
 
 Let's go through each file in the `src/client` folder and explain what it looks like, what it does, and how to use it.
 

docs/openapi-ts/tanstack-query.md

@@ -94,11 +94,11 @@ export default {
 
 :::
 
-You can now run `openapi-ts` to generate TanStack Query artifacts. 🎉
+You can now generate TanStack Query artifacts. 🎉
 
 ## Output
 
-The TanStack Query plugin will optionally generate the following output layers, depending on the input specification.
+The TanStack Query plugin will optionally generate the following artifacts, depending on the input specification.
 
 ## Queries
 

examples/openapi-ts-axios/openapi-ts.config.ts

@@ -4,8 +4,6 @@ export default defineConfig({
   client: '@hey-api/client-axios',
   input:
     'https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml',
-  // 'https://raw.githubusercontent.com/Redocly/museum-openapi-example/main/openapi.yaml',
-  // '../../packages/openapi-ts/test/spec/v3.json',
   output: {
     format: 'prettier',
     lint: 'eslint',

examples/openapi-ts-fastify/openapi-ts.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from '@hey-api/openapi-ts';
+
+export default defineConfig({
+  client: '@hey-api/client-fetch',
+  experimentalParser: true,
+  input:
+    'https://gist.githubusercontent.com/seriousme/55bd4c8ba2e598e416bb5543dcd362dc/raw/cf0b86ba37bb54bf1a6bf047c0ecf2a0ce4c62e0/petstore-v3.1.json',
+  output: {
+    format: 'prettier',
+    lint: 'eslint',
+    path: './src/client',
+  },
+  plugins: ['fastify', '@hey-api/services'],
+});

examples/openapi-ts-fastify/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@example/openapi-ts-fastify",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "openapi-ts": "openapi-ts",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hey-api/client-fetch": "workspace:*",
+    "fastify": "5.0.0",
+    "fastify-openapi-glue": "4.7.1"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "workspace:*",
+    "eslint": "9.6.0",
+    "prettier": "3.3.2",
+    "typescript": "5.5.3",
+    "vitest": "2.1.5"
+  }
+}

examples/openapi-ts-fastify/src/client/fastify.gen.ts

@@ -0,0 +1,25 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { RouteHandler } from 'fastify';
+
+import type {
+  CreatePetsResponses,
+  ListPetsData,
+  ListPetsResponses,
+  ShowPetByIdData,
+  ShowPetByIdResponses,
+} from './types.gen';
+
+export type RouteHandlers = {
+  createPets: RouteHandler<{
+    Reply: CreatePetsResponses;
+  }>;
+  listPets: RouteHandler<{
+    Querystring?: ListPetsData['query'];
+    Reply: ListPetsResponses;
+  }>;
+  showPetById: RouteHandler<{
+    Params: ShowPetByIdData['path'];
+    Reply: ShowPetByIdResponses;
+  }>;
+};

examples/openapi-ts-fastify/src/client/index.ts

@@ -0,0 +1,3 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export * from './services.gen';
+export * from './types.gen';

examples/openapi-ts-fastify/src/client/services.gen.ts

@@ -0,0 +1,60 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import {
+  createClient,
+  createConfig,
+  type Options,
+} from '@hey-api/client-fetch';
+
+import type {
+  CreatePetsError,
+  ListPetsData,
+  ListPetsError,
+  ListPetsResponse,
+  ShowPetByIdData,
+  ShowPetByIdError,
+  ShowPetByIdResponse,
+} from './types.gen';
+
+export const client = createClient(createConfig());
+
+/**
+ * List all pets
+ */
+export const listPets = <ThrowOnError extends boolean = false>(
+  options?: Options<ListPetsData, ThrowOnError>,
+) =>
+  (options?.client ?? client).get<
+    ListPetsResponse,
+    ListPetsError,
+    ThrowOnError
+  >({
+    ...options,
+    url: '/pets',
+  });
+
+/**
+ * Create a pet
+ */
+export const createPets = <ThrowOnError extends boolean = false>(
+  options?: Options<unknown, ThrowOnError>,
+) =>
+  (options?.client ?? client).post<unknown, CreatePetsError, ThrowOnError>({
+    ...options,
+    url: '/pets',
+  });
+
+/**
+ * Info for a specific pet
+ */
+export const showPetById = <ThrowOnError extends boolean = false>(
+  options: Options<ShowPetByIdData, ThrowOnError>,
+) =>
+  (options?.client ?? client).get<
+    ShowPetByIdResponse,
+    ShowPetByIdError,
+    ThrowOnError
+  >({
+    ...options,
+    url: '/pets/{petId}',
+  });

examples/openapi-ts-fastify/src/client/types.gen.ts

@@ -0,0 +1,89 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type Pet = {
+  id: number;
+  name: string;
+  tag?: string;
+};
+
+export type Pets = Array<Pet>;
+
+export type Error = {
+  code: number;
+  message: string;
+};
+
+export type ListPetsData = {
+  body?: never;
+  path?: never;
+  query?: {
+    /**
+     * How many items to return at one time (max 100)
+     */
+    limit?: number;
+  };
+};
+
+export type ListPetsErrors = {
+  /**
+   * unexpected error
+   */
+  default: Error;
+};
+
+export type ListPetsError = ListPetsErrors[keyof ListPetsErrors];
+
+export type ListPetsResponses = {
+  /**
+   * A paged array of pets
+   */
+  200: Pets;
+};
+
+export type ListPetsResponse = ListPetsResponses[keyof ListPetsResponses];
+
+export type CreatePetsErrors = {
+  /**
+   * unexpected error
+   */
+  default: Error;
+};
+
+export type CreatePetsError = CreatePetsErrors[keyof CreatePetsErrors];
+
+export type CreatePetsResponses = {
+  /**
+   * Null response
+   */
+  201: unknown;
+};
+
+export type ShowPetByIdData = {
+  body?: never;
+  path: {
+    /**
+     * The id of the pet to retrieve
+     */
+    petId: string;
+  };
+  query?: never;
+};
+
+export type ShowPetByIdErrors = {
+  /**
+   * unexpected error
+   */
+  default: Error;
+};
+
+export type ShowPetByIdError = ShowPetByIdErrors[keyof ShowPetByIdErrors];
+
+export type ShowPetByIdResponses = {
+  /**
+   * Expected response to a valid request
+   */
+  200: Pet;
+};
+
+export type ShowPetByIdResponse =
+  ShowPetByIdResponses[keyof ShowPetByIdResponses];