Resilience & fallback behavior

A real spec is rarely perfectly complete, and this plugin’s conversion layer is built around that: a missing field, an unsupported schema shape, or a security type it doesn’t recognize doesn’t break a sync or produce broken markup. It falls back sensibly and generates what it can from what’s actually there. This page covers exactly what that fallback behavior looks like.

When a field is missing#

Any field the conversion layer doesn’t find in your spec simply falls back to that block’s own registered default, the same default you’d see adding the block by hand. There’s no error and no broken markup, just a block with less filled in than one built from a more complete operation.

A whole block category can be skipped entirely when there’s nothing to build it from:

• No parameters and no request body fields: no Parameters block for that operation.
• No response has a usable example: no Response Body block, though Status Codes still generates from whatever responses exist.
• No security on the operation: no Auth block.
• No servers array in the spec at all: no Servers block.

When the spec uses something unsupported#

• A schema using allOf, oneOf, or anyOf composition still converts, using only whatever plain fields it has outside that composition. Nothing crashes; the result is just less complete for that field.
• A security scheme of type openIdConnect or mutualTLS has no matching Auth block concept. That operation is skipped for Auth specifically, not for the rest of its blocks.
• If an operation lists more than one security requirement, only the first one the plugin can model is used. The rest are silently not represented.
• A schema without a title field still converts normally, it just doesn’t get the automatic cross-link between Parameters blocks that a named schema would.
• An unresolved $ref isn’t something this plugin’s conversion layer handles at all, since it expects already-resolved data. Resolving references is WP Super Docs’ job, before your operation ever reaches this plugin.

A related case: invalid JSON in a shortcode#

This isn’t specific to the OpenAPI sync, but it’s the same kind of fallback behavior. When a block’s array-typed attribute (like Parameters’ parameters or Response Body’s responses) is passed through the shortcode’s enclosed content, and that content isn’t valid JSON, the block doesn’t break the page. It falls back to that attribute’s normal empty default and renders normally otherwise.

With WP_DEBUG turned on, an HTML comment appears in the page source right where the block would be, naming which block and which attribute failed to decode, so you can find and fix it. Without WP_DEBUG, that comment is left out and the block just renders quietly with the empty default, rather than showing broken output to a site visitor.

Tips#

• Don’t assume a thin generated page means the sync failed. Check the source spec first. Missing fields and skipped blocks are usually the spec, not an error.
• Turn on WP_DEBUG on a staging site while testing a new spec against the sync, so any shortcode JSON problems surface as visible comments instead of silently rendering empty.
• Review generated pages as drafts before publishing. Fallback behavior is designed to avoid broken output, not to guarantee a complete one.