docs agent's openapi parser dropped the security scheme, auth section missing
Fixes a docs agent whose OpenAPI parser silently drops the security scheme, leaving generated docs with no auth section. The skill shows how to verify the scheme survives parsing, fix parser config that strips extensions, and validate the auth docs end to end. It covers the securityDefinitions versus components split.
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 sectionSteps
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.
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.
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.
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