Requirements

This page covers what your setup and your OpenAPI spec need for a sync to go smoothly: what has to be active, and what shape your spec should already be in before it reaches the sync.

What needs to be active#

• Nahnu Code and API Block, installed and active. It’s the plugin that turns a parsed spec operation into block markup.
• WP Super Docs, installed and active. It’s the plugin that actually reads your spec, resolves it, and calls Nahnu Code and API Block to generate the blocks. Nahnu Code and API Block doesn’t parse OpenAPI specs on its own.
• An OpenAPI spec, in a format WP Super Docs can read. See its own documentation for supported versions and file formats.

What your spec needs to be in good shape#

By the time an operation reaches Nahnu Code and API Block’s conversion layer, it needs to be fully resolved, with no $ref pointers left in it. Resolving $refs against the rest of the document happens in WP Super Docs, before the sync calls into this plugin, so this isn’t something you do by hand, but it does mean a spec that’s hard to resolve cleanly, such as one with $refs into an external file WP Super Docs can’t reach, can produce an incomplete result.

A few other known limits, straight from the plugin itself:

• No allOf, oneOf, or anyOf schema composition. A schema that uses one of these contributes only whatever plain fields it has outside the composition.
• Only one content type is used per response or request body, for the schema shape and for the Status Codes block’s example. JSON is preferred when more than one is present.
• Security schemes of type openIdConnect or mutualTLS have no matching Auth block concept and are skipped rather than guessed at.
• If an operation lists more than one security requirement, only the first one the plugin can model becomes an Auth block.
• Type-reference linking between Parameters blocks relies on a schema’s title field being present. A schema without one still converts, just without that automatic link.

Tips#

• Give every operation a summary, and every parameter and response a description. The sync only documents what’s actually in the spec; it can’t fill in a description that isn’t there.
• Add a title to any schema you want cross-linked between Parameters blocks. Without one, that type just renders as plain text instead of a link.
• Prefer application/json for your request and response bodies when you have a choice of content type. It’s what the sync prefers too, so what you see generated will match what you wrote.