docs(openapi): document schema-level examples as selectable API Reference examples

[devin-ai-integration]

Summary

Schema-level OpenAPI/JSON Schema examples arrays on a request or response body schema (including via $ref) now each appear as a separate, selectable example in the API Reference (Example 1, Example 2, …), and the response pane gained a second "example" dropdown next to the status-code dropdown when a status code has several examples. This matters for customers whose schemas already declare multiple examples (e.g. alternative response variants such as an async-job-id vs. a completed result): all of them now show up in the docs automatically, with no need to rewrite them as x-fern-examples.

Implements docs for: feat(cli): surface every schema-level OpenAPI example as a selectable API reference example (fern-api/fern#17764) → fern-api/fern#17764
Implements docs for: feat(docs): split response example selector into status-code + example dropdowns (fern-api/fern-platform#14880) → https://github.com/fern-api/fern-platform/pull/14880

Pages changed

• fern/products/api-def/openapi/extensions/examples.mdx — new "Schema-level examples" section: behavior, a component schema with two examples entries, the precedence order (x-fern-examples > media-type example/examples > schema-level > autogenerated), and the status-code + example dropdowns in the response pane.
• fern/products/api-def/openapi/endpoints/rest.mdx — one-sentence pointer from the "Examples" section to the new section.

Validation: fern check --warnings (0 errors; remaining warnings are pre-existing and unrelated) and pre-commit/Vale on the changed files pass.

Link to Devin session: https://app.devin.ai/sessions/66b756d12bde4e2baf8fb8062e1d1685
Open in Devin Desktop: https://app.devin.ai/desktop/session/66b756d12bde4e2baf8fb8062e1d1685?variant=devin

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

🌿 Preview your docs: https://fern-preview-devin-1789837557-openapi-schema-level-examples.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

• learn/api-definitions/openapi/endpoints/http
• learn/api-definitions/openapi/extensions/request-response-examples