docs agent failed: openapi markdown export dropped request body schemas

TL;DR

Compare the markdown output against the spec: list operations with request bodies and check each has a schema section. Fix the exporter config (or switch exporters) so bodies are included, then regenerate and re-verify.

The exact error

markdown export missing request body schemas

Steps

1. Find the gaps For each operation with a requestBody in the spec, check the markdown for its schema documentation. Success check: You have the list of operations whose bodies were dropped.

2. Check the exporter config Look for options controlling body rendering depth; some exporters skip bodies by default or at certain detail levels. Success check: You know the setting that dropped the bodies.

3. Fix and regenerate Enable body rendering in the config or switch to an exporter that includes bodies, then regenerate. Success check: Every request body has its schema documented.

4. Validate completeness Re-run the comparison across all operations after regeneration. Success check: Zero operations with undocumented request bodies.

When to use

• Use when markdown API exports omit request bodies.
• Use when an agent converts OpenAPI specs to markdown.

When not to use

• Not for response schemas missing (different exporter path, same technique).
• Not for specs without request bodies (nothing to document).

Why it happens

Some markdown exporters prioritize brevity and skip request bodies unless configured otherwise. The export succeeds, so the gap is silent until a user tries to call the API from the markdown docs.

Edge cases

The comparison script is the durable check: it works regardless of exporter. Request bodies with complex nested schemas are the most likely to be dropped, so weight verification toward those.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5vbir2m-4U8eE0G8VHMGKw