Merge pull request #3573 from mikhin/nestjs

feat: add NestJS plugin

Author: mrlubos

.changeset/bright-wasps-invite.md

@@ -0,0 +1,5 @@
+---
+"@hey-api/openapi-ts": patch
+---
+
+**plugin(nestjs)**: initial release

docs/.vitepress/config/en.ts

@@ -227,6 +227,10 @@ export default defineConfig({
                 link: '/openapi-ts/plugins/fastify',
                 text: 'Fastify',
               },
+              {
+                link: '/openapi-ts/plugins/nest',
+                text: 'Nest',
+              },
               {
                 link: '/openapi-ts/plugins/adonis',
                 text: 'Adonis <span data-soon>soon</span>',
@@ -247,10 +251,6 @@ export default defineConfig({
                 link: '/openapi-ts/plugins/koa',
                 text: 'Koa <span data-soon>soon</span>',
               },
-              {
-                link: '/openapi-ts/plugins/nest',
-                text: 'Nest <span data-soon>soon</span>',
-              },
             ],
             link: '/openapi-ts/web-frameworks',
             text: 'Web Frameworks',

docs/.vitepress/theme/components/Examples.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+const props = defineProps<{
+  githubExamplePath?: string;
+}>();
+</script>
+
+<template>
+  <h2 id="examples" tabindex="-1">
+    Examples
+    <a class="header-anchor" href="#examples" aria-label="Permalink to “Examples”">​</a>
+  </h2>
+  <p>
+    You can view live examples on
+    <a
+      href="https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples"
+      target="_blank"
+      rel="noreferrer"
+      >StackBlitz</a
+    >
+    or on
+    <a
+      :href="`https://github.com/hey-api/openapi-ts/tree/main/examples${props.githubExamplePath ? props.githubExamplePath : ''}`"
+      target="_blank"
+      rel="noreferrer"
+      >GitHub</a
+    >.
+  </p>
+</template>

docs/data/people.ts

@@ -27,3 +27,8 @@ export const sebastiaanWouters: Person = {
   github: 'https://github.com/SebastiaanWouters',
   name: 'Sebastiaan Wouters',
 };
+
+export const yuriMikhin: Person = {
+  github: 'https://github.com/mikhin',
+  name: 'Yuri Mikhin',
+};

docs/openapi-ts/plugins/fastify.md

@@ -5,6 +5,7 @@ description: Generate Fastify v5 route handlers from OpenAPI with the Fastify pl
 
 <script setup lang="ts">
 import AuthorsList from '@components/AuthorsList.vue';
+import Examples from '@components/Examples.vue';
 import Heading from '@components/Heading.vue';
 import { jacobCohen } from '@data/people.js';
 import VersionLabel from '@components/VersionLabel.vue';
@@ -99,5 +100,6 @@ export default {
 
 You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/fastify/types.ts) interface.
 
-<!--@include: ../../partials/examples.md-->
+<Examples githubExamplePath="/openapi-ts-fastify" />
+
 <!--@include: ../../partials/sponsors.md-->

docs/openapi-ts/plugins/nest.md

@@ -1,18 +1,107 @@
 ---
-title: Nest
-description: Nest plugin for Hey API. Compatible with all our features.
+title: NestJS v11 Plugin
+description: Generate NestJS v11 controller methods from OpenAPI with the NestJS plugin for openapi-ts. Fully compatible with validators, transformers, and all core features.
 ---
 
 <script setup lang="ts">
-import FeatureStatus from '@components/FeatureStatus.vue';
+import AuthorsList from '@components/AuthorsList.vue';
+import Examples from '@components/Examples.vue';
+import Heading from '@components/Heading.vue';
+import { yuriMikhin } from '@data/people.js';
+import VersionLabel from '@components/VersionLabel.vue';
 </script>
 
-# Nest <span data-soon>soon</span>
+<Heading>
+  <h1>NestJS<span class="sr-only"> v11</span></h1>
+  <VersionLabel value="v11" />
+</Heading>
 
-<FeatureStatus issueNumber=1481 name="Nest" />
+::: warning
+NestJS 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).
+:::
 
 ### About
 
 [Nest](https://nestjs.com) is a progressive Node.js framework for building efficient, reliable and scalable server-side applications.
 
+The NestJS plugin for Hey API generates type-safe controller method signatures from your OpenAPI spec, fully compatible with all core features.
+
+### Collaborators
+
+<AuthorsList :people="[yuriMikhin]" />
+
+## Features
+
+- NestJS v11 support
+- seamless integration with `@hey-api/openapi-ts` ecosystem
+- type-safe controller methods
+- minimal learning curve thanks to extending the underlying technology
+
+## Installation
+
+In your [configuration](/openapi-ts/get-started), add `nestjs` to your plugins and you'll be ready to generate NestJS artifacts. :tada:
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    'nestjs', // [!code ++]
+  ],
+};
+```
+
+## Output
+
+The NestJS plugin will generate the following artifacts, depending on the input specification.
+
+## Controller Methods
+
+Operations are grouped by their first tag into separate types.
+
+::: code-group
+
+```ts [example]
+export type PetsControllerMethods = {
+  createPet: (body: CreatePetData['body']) => Promise<CreatePetResponse>;
+  listPets: (query?: ListPetsData['query']) => Promise<ListPetsResponse>;
+  showPetById: (path: ShowPetByIdData['path']) => Promise<ShowPetByIdResponse>;
+};
+
+export type StoreControllerMethods = {
+  getInventory: () => Promise<GetInventoryResponse>;
+};
+```
+
+```ts [usage]
+import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
+
+import type { PetsControllerMethods } from '../client/nestjs.gen';
+import type { CreatePetData, ListPetsData, ShowPetByIdData } from '../client/types.gen';
+
+@Controller('pets')
+export class PetsController implements Pick<
+  PetsControllerMethods,
+  'createPet' | 'listPets' | 'showPetById'
+> {
+  @Post()
+  async createPet(@Body() body: CreatePetData['body']) {}
+
+  @Get()
+  async listPets(@Query() query?: ListPetsData['query']) {}
+
+  @Get(':petId')
+  async showPetById(@Param() path: ShowPetByIdData['path']) {}
+}
+```
+
+:::
+
+## API
+
+You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/nestjs/types.ts) interface.
+
+<Examples githubExamplePath="/openapi-ts-nestjs" />
+
 <!--@include: ../../partials/sponsors.md-->

docs/openapi-ts/web-frameworks.md

@@ -13,12 +13,12 @@ Hey API natively supports the following frameworks.
 
 - [Angular](/openapi-ts/plugins/angular)
 - [Fastify](/openapi-ts/plugins/fastify)
+- [Nest](/openapi-ts/plugins/nest)
 - [Adonis](/openapi-ts/plugins/adonis) <span data-soon>Soon</span>
 - [Elysia](/openapi-ts/plugins/elysia) <span data-soon>Soon</span>
 - [Express](/openapi-ts/plugins/express) <span data-soon>Soon</span>
 - [Hono](/openapi-ts/plugins/hono) <span data-soon>Soon</span>
 - [Koa](/openapi-ts/plugins/koa) <span data-soon>Soon</span>
-- [Nest](/openapi-ts/plugins/nest) <span data-soon>Soon</span>
 
 Don't see your framework? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues).
 

eslint.config.js

@@ -59,6 +59,7 @@ export default tseslint.config(
       '**/node_modules/',
       'temp/',
       'dev/.gen/',
+      'examples/openapi-ts-nestjs/src/client/**/*.ts',
       'examples/openapi-ts-openai/src/client/**/*.ts',
       '**/test/generated/',
       '**/__snapshots__/',

examples/openapi-ts-nestjs/openapi-ts.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from '@hey-api/openapi-ts';
+
+export default defineConfig({
+  input: './openapi.json',
+  logs: {
+    path: './logs',
+  },
+  output: {
+    path: './src/client',
+    postProcess: ['oxfmt', 'eslint'],
+  },
+  plugins: ['nestjs', '@hey-api/sdk'],
+});