@hono/zod-openapi outputs examples as an array, causing incompatibility with Swagger UI

[k3ntar0]

Summary

According to the OpenAPI specification, the examples field in a response must be an object. However, when using Schema.openapi({ examples }), if examples is provided as an array, it is output as an array in the generated OpenAPI spec. This causes Swagger UI to fail to parse the examples correctly. Additionally, the examples provided in the schema are not displayed at all in Swagger UI.

Implementation

import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";

const ResourceOutputSchema = z
  .object({
    status: z.enum(["pending", "completed"]),
  })
  .openapi({
    description: "The status of the resource",
    examples: [{ status: "pending" }, { status: "completed" }],
  });

const apiDefinition = createRoute({
  method: "get",
  path: "/resource/:id",
  request: {
    params: z.object({
      id: z.string(),
    }),
  },
  responses: {
    200: {
      description: "Successful response",
      content: {
        "application/json": {
          schema: ResourceOutputSchema,
        },
      },
    },
  },
});

export const getResourceRoute = (app: OpenAPIHono) => {
  return app.openapi(apiDefinition, async (c) => {
    return c.json({ status: "completed" as const }, 200);
  });
};

Generated OpenAPI Spec

{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Example API"
  },
  "components": { "schemas": {}, "parameters": {} },
  "paths": {
    "/resource/:id": {
      "get": {
        "parameters": [
          {
            "schema": { "type": "string" },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": ["pending", "completed"]
                    }
                  },
                  "required": ["status"],
                  "description": "The status of the resource",
                  "examples": [
                    { "status": "pending" },
                    { "status": "completed" }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}

The examples provided in the schema are not displayed in Swagger UI:

Additional Notes

If my understanding is incorrect and examples being an array is intended behavior, I’d appreciate clarification. Thank you!

[noworker]

I have same issue