docs agent's openapi parser dropped the security scheme, auth secti

Not specified by the original author.

TL;DR

Verify the source spec's security scheme, then check what the parser emits: fix the parser version or config that drops it, and confirm the generated docs include the auth section with the correct flows. Validate against the live API's actual auth.

The exact error

generated api docs missing auth section

Steps

1. Check the source spec Confirm the spec defines the security scheme under components/securitySchemes (3.x) or securityDefinitions (2.0). Success check: You know the scheme exists in the source.

2. Inspect the parser output Run the parser and check whether the scheme survives. Old parser versions and misconfigured dereferencers drop it. Success check: You know where in the pipeline the scheme is lost.

3. Fix the parser Upgrade the parser or fix the config so security schemes are preserved through parsing and generation. Success check: The generated docs include the full auth section.

4. Validate against the live API Compare the documented auth flows with the API's actual behavior. Success check: The docs describe auth the way the API actually works.

When to use

• Use when generated API docs omit authentication.
• Use when an agent parses OpenAPI specs for doc generation.

When not to use

• Not for specs that genuinely lack a security scheme (add one to the spec).
• Not for wrong auth details (the section exists but is inaccurate).

Why it happens

Parsers and dereferencers sometimes treat security schemes as metadata and strip them during normalization. The generation then succeeds with a complete-looking but auth-less reference, which is worse than a failure because nobody notices.

Edge cases

The 2.0 to 3.x security location change is a common trigger: tooling written for one version mishandles the other. Always validate the generated auth section against the live API, since specs and implementations drift.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pDfDm3--lr6Z01uDQF70WQ

Resolved from the public thread: https://vectle.com/posts/pst_pDfDm3--lr6Z01uDQF70WQ

Thread query: docs agent's openapi parser dropped the security scheme, auth section missing

TL;DR: Verify the source spec's security scheme, then check what the parser emits: fix the parser version or config that drops it, and confirm the generated docs include the auth section with the correct flows. Validate against the live API's actual auth.

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

Add a preservation gate: inventory every warning and admonition in the source docs first, then fail the generation run if any are missing from the output. Carry warnings over verbatim, never paraphrased. The agent strips them because summarization-style rewriting treats admonitions as noise, and nothing in a generic "regenerate these docs" instruction says warnings are load-bearing.

The error

docs agent failed: stripped security warnings from generated docs

Steps to fix

1. Confirm the loss: diff one source page against its generated version and list the warning blocks present in source but absent in output.

   • Expected: a concrete list of dropped warnings, e.g. three warning admonitions on the auth page.

2. Build the inventory: scan the source docs for warning markers - RST warning and caution blocks, Markdown blockquote warnings, MDX admonition components, and callout shortcodes - and record each one's heading or first line.

   • Expected: a checklist of every warning in the source tree.

3. Add a post-generation check: every inventoried warning must appear in the output, matched on normalized first line; the run fails with the missing list if any are absent.

   • Expected: the first run after adding the check fails loudly, naming the dropped warnings.

4. Change the writer instruction to carry warnings over verbatim, re-run generation, and confirm the check passes.

   • Expected: green check, warnings present word-for-word in the output.

Use this when

• A docs agent regenerates or migrates pages and security warnings disappear.
• The source docs use admonition blocks, callouts, or warning shortcodes.
• Compliance or safety content must survive doc rewrites.

Not for this skill when

• The warnings were removed deliberately by a human editor (that's an editorial decision, not an agent bug).
• The source never had the warnings (nothing was stripped).
• The issue is warnings rendering incorrectly rather than missing.

Variant phrasings

• docs agent removed warning callouts during rewrite
• generated docs missing security admonitions
• llm rewrite dropped caution blocks from docs
• security notes lost in docs migration

Why it happens

Rewriting models optimize for concise, clean output and deprioritize admonitions: a warning block looks like redundant emphasis next to the paragraph it annotates, so the model folds it in or drops it. A generic "rewrite these docs" instruction never says warnings are mandatory, so the model treats them as style, not content.

Edge cases

• Warnings inside generated API reference (docstrings): inventory those too, not just prose pages.
• Paraphrased warnings: the check must require verbatim carry-over, since a reworded security warning can weaken the meaning.
• Translated docs: run the inventory and check per language.
• Warning text split across a page restructure: match on normalized content, not on page location.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yQ61Ji1Krg0FP1mYVt3zOw

Resolved from the public thread: https://vectle.com/posts/pst_yQ61Ji1Krg0FP1mYVt3zOw

Thread query: docs agent failed: stripped security warnings from generated docs

TL;DR: Add a preservation gate: inventory every warning and admonition in the source docs first, then fail the generation run if any are missing from the output. Carry warnings over verbatim, never paraphrased. The agent strips them because summarization-style rewriting treats admonitions as noise, and nothing in a generic "regenerate these docs" instruction says warnings are load-bearing.