Docs
← Back to site

OpenAPI IntegrationUpdated

4 min readUpdated November 21, 2026

If you’re documenting a REST API, you don’t have to hand-write a doc for every endpoint. Attach an OpenAPI 3.x spec to a category, and WP Super Docs generates one draft doc per endpoint automatically, using Nahnu Code Block for presentation.

This feature is in Beta.

Requirements#

  • The free Nahnu Code Block add-on (v3 or later) must be active (see Add-ons). Endpoint documentation is built using its OpenAPI-specific block API. See wpcodeapiblock.com for more on the plugin itself.
  • Your spec must be OpenAPI 3.x, in JSON or YAML.

Turning it on#

Go to Settings → Integrations → OpenAPI and enable it. If Nahnu Code Block isn’t active yet, you’ll see a warning with a direct link to install it, both here and as an admin notice on WP Super Docs screens generally, and syncing won’t work until it’s active.

Attaching a spec to a category#

Go to WP Super Docs → Doc Categories (see The Doc Categories Page), find your category, and click its OpenAPI button (only shown when this feature is enabled). This expands an inline panel with a spec URL field. Paste your spec’s URL and click Save URL.

The OpenAPI panel open on a category, with the spec URL and Sync now.

Syncing#

In that same panel, click Sync now to sync just this category. You’ll see a spinner while it runs, with results shown inline once it finishes, including a link to the first generated doc.

To sync every category that has a spec URL configured at once, regardless of which product they belong to, go to Settings → Integrations → OpenAPI and click Sync all OpenAPI categories instead.

The OpenAPI settings on the Integrations tab.

What gets generated#

One draft doc per endpoint (operation) in the spec. Depending on what that specific operation actually defines in the spec, a generated doc can include:

  • Endpoint: method, path, and summary (with a deprecation notice if the spec marks it deprecated)
  • Servers: base URLs, if the spec defines any
  • Auth: the authentication scheme for that operation, if it requires one
  • Parameters: path, query, header, and request body parameters, if there are any
  • Response Body
  • Status Codes
  • A cURL example

Not every generated doc will have every block, an endpoint with no parameters simply won’t get a Parameters block. Every value comes directly from your spec; nothing is invented.

Block generation is fully delegated to Nahnu Code Block’s own OpenAPI-aware component, which covers a number of details beyond the basic fields: an auth-required badge, example values shown alongside defaults on parameters, cross-links between related type references, a toggle to show the full schema, response headers, range and pattern badges on constrained fields, read-only and write-only pills, nullable indicators, the endpoint’s description, links to related endpoints, the operation ID, and multiple named examples where a spec provides more than one.

If your spec uses shared, reusable components ($ref pointers to schemas defined once and referenced from multiple endpoints, a common pattern in real-world specs), those references are resolved automatically, so a parameter or response body defined via a shared component renders with its real fields, not an empty placeholder. References to an external file are logged and skipped rather than followed, since resolving those would mean an extra outbound request per reference.

If an operation defines callbacks (webhook-style operations the API will call back to you), those are included in the generated doc too, using the same block types as the main endpoint.

Generated docs are created as drafts, so nothing goes live until you review and publish them yourself.

Re-syncing is safe for edits you’ve made#

If you’ve added your own content to a generated doc, an intro paragraph, a note, extra examples, re-syncing won’t touch it. Only the specific generated block group is replaced; anything you’ve written before it, after it, or in between is left exactly as you left it.

If an endpoint is removed from your spec#

Its doc is moved to Trash, not permanently deleted. If you removed it by mistake, or the spec change gets reverted, you can restore it from Trash rather than having to regenerate it.

Spec formats#

JSON is tried first regardless of what the URL looks like. For YAML, WP Super Docs uses PHP’s native yaml extension if your server has it installed, and falls back to a bundled pure-PHP parser if not, so YAML specs work either way with no server configuration required.

With Claude#

With OpenAPI support turned on and Claude connected, an Administrator can ask Claude to do both steps: “Use https://api.example.com/openapi.json as the spec for the API Reference category, then create the docs.” Claude sets the category’s spec URL and runs the sync, which creates or updates one draft doc per endpoint, exactly like Sync now.

Setting the spec URL changes the category, so like other category changes it needs your site to let Claude publish. The sync itself also needs that once docs from an earlier sync are published, because it changes live docs.

Was this helpful?

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only