API Parameter description output to wrong place

[kernwig]

The output OpenAPI spec does not place the description of a (query string) parameter in the right place, and thus is lost when rendered.

Example:

const getServiceAreasRequestSchema = z
  .object({
    clientBC: z.string().describe("Business code identifying the Client"),
  });

// ... elsewhere ....

import { OpenApiGeneratorV3, OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";

// ...

  registry.registerPath({
    path: "/clients/getServiceAreas",
    method: "get",
    request: { query: getServiceAreasRequestSchema },
    responses: {
      "200": { content: { "application/json": { schema: serviceAreaSchema.array() } }  },
    },
  });

Results in OpenAPI spec:

  /clients/getServiceAreas:
    get:
      parameters:
        - schema:
            type: string
            minLength: 1
            description: Business code identifying the Client
          required: true
          name: clientBC
          in: query
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ServiceArea"

The description: Business code identifying the Client belongs one element up, next to the parameter name and required. See https://swagger.io/docs/specification/describing-parameters/

As a result, the description is not rendered by Swagger UI.

[AGalabov]

@kernwig thank you for that. I do see this and agree that this should be fixed. I'll try and do that whenever I can. In the mean time what I can suggest is using .openapi({ param: { description: '<your-description-here>' }}) as a temporary solution

[AGalabov]

@kernwig should be fixed as part of v6.2.0.

As a side comment. I've decided to provide the description in both cases. Because from an "API" point of view:

      request: {
        query: z.object({
          test: z.string().describe('Some parameter'), // You'd expect this to be on a parameter level
        }),
      },

but also

const schema = z
     .string()
     .describe('Some parameter')
     .openapi('SomeString'); // You'd also expect the description to be a part of the schema 
//...
request: {
  query: z.object({ test: schema }), // You'd expect this to be on a parameter level
},

Note: having in both places should not be a problem for swagger documentation rendering and validation tools.

Let me know if there is anything else I can be helpful with.

[kernwig]

Confirmed problem fixed. 👍 Thank you for the quick fix, and the great library!