fix(ts-rest-open-api): pathParams and query descriptions from zod .describe() (#364)

Move `"description"` out of `"schema"` as per OpenAPI spec:
https://spec.openapis.org/oas/v3.1.0#parameter-object

Fixes #305

Author: llllvvuu

.changeset/new-kids-add.md

@@ -0,0 +1,5 @@
+---
+"@ts-rest/open-api": patch
+---
+
+fix(ts-rest-open-api): pathParams and query descriptions from `zod` `.describe()`

libs/ts-rest/open-api/src/lib/ts-rest-open-api.spec.ts

@@ -68,7 +68,7 @@ const postsRouter = c.router({
     method: 'GET',
     path: `/posts/:id/comments/:commentId`,
     pathParams: z.object({
-      commentId: z.string().length(5),
+      commentId: z.string().length(5).describe("the comment ID"),
     }),
     responses: {
       200: c.response<Post | null>(),
@@ -324,6 +324,7 @@ const expectedApiDoc = {
             in: 'path',
             name: 'commentId',
             required: true,
+            description: 'the comment ID',
             schema: {
               type: 'string',
               minLength: 5,
@@ -571,7 +572,7 @@ describe('ts-rest-open-api', () => {
           },
           query: z
             .object({
-              foo: z.string(),
+              foo: z.string().describe("Foo"),
             })
             .refine((v) => v.foo === 'bar', {
               message: 'foo must be bar',
@@ -596,6 +597,7 @@ describe('ts-rest-open-api', () => {
               description: undefined,
               parameters: [
                 {
+                  description: 'Foo',
                   in: 'query',
                   name: 'foo',
                   required: true,

libs/ts-rest/open-api/src/lib/ts-rest-open-api.ts

@@ -78,12 +78,16 @@ const getPathParameters = (path: string, zodObject?: unknown) => {
     })) || [];
 
   if (isZodObj) {
-    const paramsFromZod = Object.entries(zodShape).map(([key, value]) => ({
-      name: key,
-      in: 'path' as const,
-      required: true,
-      schema: getOpenApiSchemaFromZod(value),
-    }));
+    const paramsFromZod = Object.entries(zodShape).map(([key, value]) => {
+      const { description, ...schema } = getOpenApiSchemaFromZod(value)!;
+      return {
+        name: key,
+        in: 'path' as const,
+        required: true,
+        schema,
+        ...(description && { description }),
+      }
+    });
 
     params.push(...paramsFromZod);
   }
@@ -125,13 +129,14 @@ const getQueryParametersFromZod = (zodObject: unknown, jsonQuery = false) => {
   const zodShape = extractZodObjectShape(zodObject);
 
   return Object.entries(zodShape).map(([key, value]) => {
-    const schema = getOpenApiSchemaFromZod(value)!;
+    const { description, ...schema } = getOpenApiSchemaFromZod(value)!;
     const isObject = (value as z.ZodTypeAny)._def.typeName === 'ZodObject';
     const isRequired = !(value as z.ZodTypeAny).isOptional();
 
     return {
       name: key,
       in: 'query' as const,
+      ...(description && { description }),
       ...(isRequired && { required: true }),
       ...(jsonQuery
         ? {