feat(openapi): support name, id, summary, and description in example objects

[lx3133584]

Problem

When examples are specified on OpenAPI 3.0 schema definitions, convertExamplesArrayToObject unconditionally generated auto-incrementing keys (example1, example2) and wrapped the entire object under { value: ... }. This made it impossible for users to specify custom example names/IDs or attach summary, description, or externalValue attributes as supported by the OpenAPI 3.0 Example Object specification.

Solution

• Updated convertExamplesArrayToObject to inspect if an example element is an OpenAPI 3.0 Example Object (containing value or externalValue).
• When detected, preserves summary, description, and other Example Object properties, using example.name or example.id as the key (falling back to exampleN).
• Preserved backward compatibility for plain object and primitive examples.

Testing

• Added unit tests in test/spec/openapi/option.test.js verifying preservation of summary, description, and custom example names/IDs.
• Verified all 267 unit tests pass with 100% statement, branch, function, and line coverage, and TypeScript tests pass cleanly.

[Copilot]

Pull request overview

Extends OpenAPI example conversion to preserve Example Object metadata and custom keys.

Changes:

• Detects Example Objects using value or externalValue.
• Uses name, id, or generated keys.
• Adds request-body coverage for metadata preservation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
lib/spec/openapi/utils.js	Adds Example Object conversion logic.
test/spec/openapi/option.test.js	Tests metadata and custom example keys.

Suppressed comments (3)

lib/spec/openapi/utils.js:125

• This shape check breaks backward compatibility for ordinary object payloads that happen to contain value or externalValue. For example, an object schema with examples: [{ value: 42 }, { value: 43 }] previously emitted those objects as the example values; it now emits 42 and 43, changing the payload and potentially making it violate its schema. A schema example can legally use any property names, so Example Objects need an explicit, non-colliding opt-in (or a separate input field) rather than being inferred solely from payload keys.

      if ('value' in example || 'externalValue' in example) {

lib/spec/openapi/utils.js:125

• The new Example Object handling only runs when there are multiple examples. schemaToMedia sends a one-element array directly to media.example, so [{ name: 'first', summary: '...', value: payload }] is still emitted as the raw payload { name, summary, value } instead of an examples map and loses the intended Example Object semantics. Route a single detected Example Object through this converter as well and cover that case.

      if ('value' in example || 'externalValue' in example) {

lib/spec/openapi/utils.js:128

• A custom name of __proto__ invokes the accumulator object's prototype setter instead of creating an examples-map entry, so that example disappears from serialized output and its object becomes the accumulator prototype. Define an own property explicitly (or use a prototype-free map) for user-controlled keys.

        examplesObject[name] = exampleObj

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Tony133]

Thanks for the PR. Closing because detecting Example Objects by the presence of value/externalValue changes the output for existing users whose payloads legitimately contain those keys, so this is a breaking change rather than an additive feature. It also doesn't cover the single-example path and allows __proto__ as a key.

Note that named examples with summary/description are already supported through the x-examples field (see the README), which is the explicit opt-in for this use case.