Experiment: can <Schema> render SWML schemas no operation references?

[fern-api]

Summary

Throwaway experiment (do not merge) to answer: if a schema exists in components.schemas but no operation references it, can <Schema type="..."> still render it?

Setup, using messaging SWML as the test subject:

1. Dropped the only three operation references to messaging SWML in TypeSpec (swml-scripts core + create/update requests):

   - contents: SWML.Messaging.SWMLObject;
   + contents: unknown;

   With no reference left, the TypeSpec OpenAPI emitter stops emitting all 16 SWML.Messaging.* schemas — so "leave the definitions in the spec" needs a second step.
2. Re-added those 16 schemas verbatim as orphans via a new fern/apis/signalwire-rest/openapi-overrides.yaml, wired up in generators.yml:

   - openapi: openapi.yaml
     overrides: openapi-overrides.yaml

   Net result: SWML.Messaging.* is present in the merged spec and reachable from zero operations, requests, responses, webhooks or channels.
3. Swapped the hand-written ParamField blocks on the reply page for the equivalent schema refs:

   <Schema type="SWML.Messaging.ReplyWithBody" api="signalwire-rest" showDescription />
   <Schema type="SWML.Messaging.ReplyInlineSwitch" api="signalwire-rest" showDescription />

   The string-shorthand tab keeps its ParamField (a bare string has no schema to point at).

Definition-level result so far (local fern fdr): all orphan types survive the OpenAPI → Fern → FDR conversion, including nested refs (SwmlMessagingReplyWithBody, SwmlMessagingReplyInlineSwitch, SwmlMessagingSwitchTransform, …), with 0 errors. Whether the docs frontend resolves them for <Schema> is what the preview on this PR decides.

Note the calling side is deliberately untouched: making contents unknown on both union variants of SwmlScript/SwmlScriptCreateRequest makes the variants indistinguishable and breaks example validation ("Missing discriminant property (script_type)"), so only the messaging variant was loosened.

Requested by: Fern Support

[fern-api]

Requested by: Devon White
Slack thread: View conversation

[github-actions]

🌿 Preview

https://signalwire-preview-docs-620.docs.buildwithfern.com/docs

---

View workflow run