Improve OpenAPI generation

This change improves the OpenAPI spec
generation by introducing auto-generated
schema objects that can be used across
different operations.

Additionally, swagger-cli is introduced as
part of the CI pipeline to validate that the
generated OpenAPI document is valid.

apps/example/src/app/api/routes/rpc/route.ts

@@ -11,40 +11,39 @@ const TODOS = [
 
 // Example App Router RPC handler.
 export const POST = rpcRouteHandler({
-  getTodos: rpcOperation({
-    // Optional OpenAPI operation documentation.
-    operationId: 'getTodos',
-    tags: ['example-api', 'todos', 'app-router', 'rpc']
-  })
+  getTodos: rpcOperation()
     // Output schema for strictly-typed responses and OpenAPI documentation.
     .output([
-      z.array(
-        z.object({
-          id: z.number(),
-          name: z.string(),
-          completed: z.boolean()
-        })
-      )
+      {
+        schema: z.array(
+          z.object({
+            id: z.number(),
+            name: z.string(),
+            completed: z.boolean()
+          })
+        )
+      }
     ])
     .handler(() => {
       // Type-checked response.
       return TODOS;
     }),
 
-  getTodoById: rpcOperation({
-    operationId: 'getTodoById',
-    tags: ['example-api', 'todos', 'app-router', 'rpc']
-  })
+  getTodoById: rpcOperation()
     .input(z.string())
     .output([
-      z.object({
-        error: z.string()
-      }),
-      z.object({
-        id: z.number(),
-        name: z.string(),
-        completed: z.boolean()
-      })
+      {
+        schema: z.object({
+          error: z.string()
+        })
+      },
+      {
+        schema: z.object({
+          id: z.number(),
+          name: z.string(),
+          completed: z.boolean()
+        })
+      }
     ])
     .handler((id) => {
       const todo = TODOS.find((t) => t.id === Number(id));
@@ -58,32 +57,25 @@ export const POST = rpcRouteHandler({
       return todo;
     }),
 
-  createTodo: rpcOperation({
-    // Optional OpenAPI operation documentation.
-    operationId: 'createTodo',
-    tags: ['example-api', 'todos', 'app-router', 'rpc']
-  })
+  createTodo: rpcOperation()
     // Input schema for strictly-typed request, request validation and OpenAPI documentation.
     .input(
       z.object({
         name: z.string()
       })
     )
     // Output schema for strictly-typed responses and OpenAPI documentation.
-    .output([z.object({ message: z.string() })])
+    .output([{ schema: z.object({ message: z.string() }) }])
     .handler(async ({ name }) => {
       // Type-checked response.
       return { message: `New TODO created: ${name}` };
     }),
 
-  deleteTodo: rpcOperation({
-    operationId: 'deleteTodo',
-    tags: ['example-api', 'todos', 'app-router', 'rpc']
-  })
+  deleteTodo: rpcOperation()
     .input(z.string())
     .output([
-      z.object({ error: z.string() }),
-      z.object({ message: z.string() })
+      { schema: z.object({ error: z.string() }) },
+      { schema: z.object({ message: z.string() }) }
     ])
     .handler((id) => {
       // Delete todo.

apps/example/src/app/api/routes/todos/route.ts

@@ -58,12 +58,14 @@ const handler = routeHandler({
       {
         status: 201,
         contentType: 'application/json',
-        schema: z.string()
+        schema: z.string(),
+        name: 'CreateTodoSuccessResponse' // Optional name for OpenAPI spec.
       },
       {
         status: 401,
         contentType: 'application/json',
-        schema: z.string()
+        schema: z.string(),
+        name: 'CreateTodoUnauthorizedResponse' // Optional name for OpenAPI spec.
       }
     ])
     // Optional middleware logic executed before request validation.

package.json

@@ -8,14 +8,15 @@
     "test:watch": "pnpm --filter next-rest-framework run test:watch",
     "type-check": "pnpm run -r type-check",
     "format": "prettier --write '**/*.{ts,json}' && eslint --fix --max-warnings=0 --ext=.ts .",
-    "lint": "prettier --check '**/*.{ts,json}' && eslint --max-warnings=0 --ext=.ts .",
+    "lint": "prettier --check '**/*.{ts,json}' && eslint --max-warnings=0 --ext=.ts . && swagger-cli validate ./apps/example/public/openapi.json",
     "ci": "pnpm run build && pnpm run type-check && pnpm run lint && pnpm run test"
   },
   "dependencies": {
     "react": "18.2.0",
     "react-dom": "18.2.0"
   },
   "devDependencies": {
+    "@apidevtools/swagger-cli": "4.0.4",
     "@types/node": "20.5.4",
     "@types/react": "18.2.21",
     "@types/react-dom": "18.2.7",

packages/next-rest-framework/src/app-router/route-handler.ts

@@ -1,21 +1,19 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { DEFAULT_ERRORS, NEXT_REST_FRAMEWORK_USER_AGENT } from '../constants';
-import { type BaseQuery } from '../types';
+import { type OpenApiPathItem, type BaseQuery } from '../types';
 import {
-  getPathsFromMethodHandlers,
+  getOasDataFromMethodHandlers,
   isValidMethod,
   validateSchema,
   logNextRestFrameworkError
 } from '../shared';
 
 import { type ValidMethod } from '../constants';
 
-import { type OpenAPIV3_1 } from 'openapi-types';
-
 import { type RouteOperationDefinition } from './route-operation';
 
 export interface RouteParams {
-  openApiPath?: OpenAPIV3_1.PathItemObject;
+  openApiPath?: OpenApiPathItem;
   [ValidMethod.GET]?: RouteOperationDefinition;
   [ValidMethod.PUT]?: RouteOperationDefinition;
   [ValidMethod.POST]?: RouteOperationDefinition;
@@ -54,7 +52,7 @@ export const routeHandler = (methodHandlers: RouteParams) => {
         const route = decodeURIComponent(pathname ?? '');
 
         try {
-          const nrfOasData = getPathsFromMethodHandlers({
+          const nrfOasData = getOasDataFromMethodHandlers({
             methodHandlers,
             route
           });
@@ -72,7 +70,7 @@ ${error}`);
         return handleMethodNotAllowed();
       }
 
-      const { input, handler, middleware } = methodHandler._config;
+      const { input, handler, middleware } = methodHandler._meta;
 
       if (middleware) {
         const res = await middleware(new NextRequest(req.clone()), context);
@@ -163,7 +161,7 @@ ${error}`);
   };
 
   handler.getPaths = (route: string) =>
-    getPathsFromMethodHandlers({
+    getOasDataFromMethodHandlers({
       methodHandlers,
       route
     });

packages/next-rest-framework/src/app-router/route-operation.ts

@@ -1,14 +1,14 @@
 /* eslint-disable @typescript-eslint/no-invalid-void-type */
 
-import { type OpenAPIV3_1 } from 'openapi-types';
 import {
   type BaseStatus,
   type BaseQuery,
   type InputObject,
   type OutputObject,
   type BaseContentType,
   type Modify,
-  type AnyCase
+  type AnyCase,
+  type OpenApiOperation
 } from '../types';
 import { type NextRequest, type NextResponse } from 'next/server';
 import { type z } from 'zod';
@@ -216,16 +216,16 @@ type NextRouteHandler = (
 ) => Promise<NextResponse> | NextResponse | Promise<void> | void;
 
 export interface RouteOperationDefinition {
-  _config: {
-    openApiOperation?: OpenAPIV3_1.OperationObject;
+  _meta: {
+    openApiOperation?: OpenApiOperation;
     input?: InputObject;
     output?: readonly OutputObject[];
     middleware?: NextRouteHandler;
     handler?: NextRouteHandler;
   };
 }
 
-type RouteOperation = (openApiOperation?: OpenAPIV3_1.OperationObject) => {
+type RouteOperation = (openApiOperation?: OpenApiOperation) => {
   input: RouteInput<true>;
   output: RouteOutput<true>;
   middleware: (middleware?: RouteHandler) => {
@@ -241,7 +241,7 @@ export const routeOperation: RouteOperation = (openApiOperation) => {
     middleware: Middleware | undefined,
     handler: Handler | undefined
   ): RouteOperationDefinition => ({
-    _config: {
+    _meta: {
       openApiOperation,
       input,
       output,

packages/next-rest-framework/src/app-router/rpc-route-handler.ts

@@ -11,11 +11,16 @@ import {
 } from '../shared';
 import { type Client } from '../client/rpc-client';
 import { type OperationDefinition } from '../shared/rpc-operation';
+import { type OpenApiOperation, type OpenApiPathItem } from '../types';
 
 export const rpcRouteHandler = <
   T extends Record<string, OperationDefinition<any, any>>
 >(
-  operations: T
+  operations: T,
+  options?: {
+    openApiPath?: OpenApiPathItem;
+    openApiOperation?: OpenApiOperation;
+  }
 ) => {
   const handler = async (req: NextRequest) => {
     try {
@@ -43,7 +48,8 @@ export const rpcRouteHandler = <
         try {
           const nrfOasData = getOasDataFromRpcOperations({
             operations,
-            route
+            route,
+            options
           });
 
           return NextResponse.json({ nrfOasData }, { status: 200 });
@@ -136,6 +142,7 @@ ${error}`);
   handler.getPaths = (route: string) =>
     getOasDataFromRpcOperations({
       operations,
+      options,
       route
     });
 

packages/next-rest-framework/src/pages-router/api-route-handler.ts

@@ -4,17 +4,17 @@ import {
   type ValidMethod
 } from '../constants';
 import {
-  getPathsFromMethodHandlers,
+  getOasDataFromMethodHandlers,
   isValidMethod,
   validateSchema,
   logNextRestFrameworkError
 } from '../shared';
 import { type NextApiRequest, type NextApiResponse } from 'next/types';
-import { type OpenAPIV3_1 } from 'openapi-types';
 import { type ApiRouteOperationDefinition } from './api-route-operation';
+import { type OpenApiPathItem } from '../types';
 
 export interface ApiRouteParams {
-  openApiPath?: OpenAPIV3_1.PathItemObject;
+  openApiPath?: OpenApiPathItem;
   [ValidMethod.GET]?: ApiRouteOperationDefinition;
   [ValidMethod.PUT]?: ApiRouteOperationDefinition;
   [ValidMethod.POST]?: ApiRouteOperationDefinition;
@@ -46,7 +46,7 @@ export const apiRouteHandler = (methodHandlers: ApiRouteParams) => {
         const route = decodeURIComponent(pathname ?? '');
 
         try {
-          const nrfOasData = getPathsFromMethodHandlers({
+          const nrfOasData = getOasDataFromMethodHandlers({
             methodHandlers,
             route
           });
@@ -66,7 +66,7 @@ ${error}`);
         return;
       }
 
-      const { input, handler, middleware } = methodHandler._config;
+      const { input, handler, middleware } = methodHandler._meta;
 
       if (middleware) {
         await middleware(req, res);
@@ -132,7 +132,7 @@ ${error}`);
   };
 
   handler.getPaths = (route: string) =>
-    getPathsFromMethodHandlers({
+    getOasDataFromMethodHandlers({
       methodHandlers,
       route
     });

packages/next-rest-framework/src/pages-router/api-route-operation.ts

@@ -6,14 +6,14 @@ import {
   type AnyCase,
   type BaseQuery,
   type BaseStatus,
-  type BaseContentType
+  type BaseContentType,
+  type OpenApiOperation
 } from '../types';
 import {
   type NextApiRequest,
   type NextApiHandler,
   type NextApiResponse
 } from 'next/types';
-import { type OpenAPIV3_1 } from 'openapi-types';
 import { type z } from 'zod';
 
 type TypedNextApiRequest<Body, Query> = Modify<
@@ -148,16 +148,16 @@ type ApiRouteInput<Middleware extends boolean = false> = <
   : Record<string, unknown>);
 
 export interface ApiRouteOperationDefinition {
-  _config: {
-    openApiOperation?: OpenAPIV3_1.OperationObject;
+  _meta: {
+    openApiOperation?: OpenApiOperation;
     input?: InputObject;
     output?: readonly OutputObject[];
     middleware?: NextApiHandler;
     handler?: NextApiHandler;
   };
 }
 
-type ApiRouteOperation = (openApiOperation?: OpenAPIV3_1.OperationObject) => {
+type ApiRouteOperation = (openApiOperation?: OpenApiOperation) => {
   input: ApiRouteInput<true>;
   output: ApiRouteOutput<true>;
   middleware: (middleware?: ApiRouteHandler) => {
@@ -173,7 +173,7 @@ export const apiRouteOperation: ApiRouteOperation = (openApiOperation) => {
     middleware: Middleware | undefined,
     handler: Handler | undefined
   ): ApiRouteOperationDefinition => ({
-    _config: {
+    _meta: {
       openApiOperation,
       input,
       output,