Skip to content

Property description not showing up in generated OpenAPI spec #3059

@shadone

Description

@shadone

Description

When I my schema like this

const HelloRequestSchema = z.object({
  name: z.string()
    .describe("The name to say hello to")
    // also tried
    .meta({
      description: "The name to say hello to",
    })
});

The generated OpenAPI spec does not have the description field. What I get is this

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /hello:
    post:
      operationId: HelloWorld
      summary: Hello World
      description: My description
      requestBody:
        description: POST /hello Request body
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
        required: true

Reproduction

import {
  createConfig,
  Routing,
  Documentation,
  defaultEndpointsFactory,
} from "express-zod-api";
import { z } from "zod";

const config = createConfig({
  startupLogo: false,
  cors: true,
  http: {
    listen: 8080,
  },
});

const HelloRequestSchema = z.object({
  name: z.string()
    .describe("The name to say hello to")
    // also tried
    .meta({
      description: "The name to say hello to",
    })
});

const HelloResponseSchema = z.object({
  message: z.string().describe("The hello message"),
});

type HelloResponse = z.infer<typeof HelloResponseSchema>;

const helloEndpoint = defaultEndpointsFactory.build({
  operationId: "HelloWorld",
  shortDescription: "Hello World",
  description: "My description",
  method: "post",
  input: HelloRequestSchema,
  output: HelloResponseSchema,
  handler: async ({ input }): Promise<HelloResponse> => {
    return {
      message: "Hello World",
    };
  },
});

const routing: Routing = {
  hello: helloEndpoint,
};

const openApiSpecAsYamlString = new Documentation({
  routing,
  config,
  version: "1.0.0",
  title: "My API",
  serverUrl: "https://example.com",
  // composition: "components", // optional, or "components" for keeping schemas in a separate dedicated section using refs
  // descriptions: {
  //   requestBody: (props) => `${props.operationId} Request`,
  //   requestParameter: ({ operationId }) => `${operationId} Parameter`,
  //   negativeResponse: ({ operationId }) => `${operationId} Error Response`,
  //   positiveResponse: ({ operationId }) => `${operationId} Success Response`,
  // },
}).getSpecAsYaml();

console.log(openApiSpecAsYamlString);

Context

  • Node.js version: v25.2.0
  • express-zod-api version: 25.6.0

Metadata

Metadata

Assignees

No one assigned

    Labels

    external bugit's a bug, but in a dependency

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions