How the sync works

The OpenAPI sync is how WP Super Docs turns your OpenAPI spec into ready-to-edit documentation pages, built out of this plugin’s own blocks (Endpoint, Parameters, Response Body, Status Codes, Auth) instead of a fixed template. Each operation in your spec becomes a page it can generate, with every field already mapped onto the matching block settings.

What triggers a sync#

Nahnu Code and API Block is the conversion layer, not the sync itself. It turns one already-parsed OpenAPI operation into ready block markup, but it doesn’t fetch your spec file, decide when to re-check it, or own any sync button or schedule. Parsing the spec and deciding when to run is WP Super Docs’ job.

For exactly how and when WP Super Docs kicks off a sync, whether that’s a manual action you trigger yourself or something it also checks on a schedule, see WP Super Docs’ own documentation or settings. This page covers what happens once a sync runs, not what starts it.

What happens during a sync#

1. WP Super Docs reads your OpenAPI spec and resolves any $ref references, so each operation arrives as a plain, complete set of data with nothing left pointing elsewhere in the document.
2. For each operation, it hands that data to this plugin, which converts it into a stack of ready block markup: an Endpoint block, and whichever of Parameters, Response Body, Status Codes, and Auth actually apply to that operation.
3. That block markup is inserted as a new page, landing as a draft rather than published outright, so it can be reviewed before it goes live.
4. The result opens in the ordinary block editor, exactly as if you’d built it by hand. You can edit, rearrange, or delete anything the sync generated.

How fields map onto blocks#

Each OpenAPI operation’s fields map onto blocks roughly like this:

From your spec	Becomes
Method, path, summary, description, deprecated, operationId, security	The Endpoint block
Parameters, and any request body fields	The Parameters block
Responses with an example body	The Response Body block
Every response, with or without an example	The Status Codes block
The operation’s security requirement	The Auth block
Your spec’s top-level servers array	A Servers block

See What Gets Generated for the full field-by-field breakdown.

Tips#

• Review generated pages before publishing them. A sync is a starting point, not a finished page, and it lands as a draft for exactly that reason.
• Keep your spec’s summary and description fields filled in. The sync only documents what’s actually in the spec; it can’t invent a description that isn’t there.
• If a page a sync generated looks off, check the source OpenAPI spec first. The conversion follows your spec’s structure closely, so an unexpected result is often the spec, not the sync.