docs show deprecated parameter as required, integration broken

TL;DR

Mark the parameter deprecated - not required - in the source the docs generate from, then rebuild and republish. Integrations break because clients trust the "required" label and send a field the server now ignores or rejects. The fix belongs in the spec or docstring, never as a hand-edit on the built HTML.

The error

docs show deprecated parameter as required, integration broken

Steps

1. Find the source of truth: the OpenAPI spec file or the function docstring where the parameter is declared. Expected: you locate the required: true declaration or the "required" wording.
2. Change it: in OpenAPI set deprecated: true and required: false, and note the replacement parameter; in a docstring, remove the "required" wording and add a deprecation notice with the successor. Expected: the source no longer claims the parameter is required.
3. Regenerate or rebuild the docs. Expected: the build exits 0.
4. Open the built page for that endpoint or function. Expected: the parameter renders as deprecated or optional, with no "required" label.
5. Notify the integration owners who built against the old docs, pointing at the corrected page. Expected: they confirm the updated contract.

Use this when

• Docs label a parameter "required" that the API treats as deprecated.
• An integration fails because it sends a deprecated field the docs demanded.
• A parameter was deprecated in code but the docs were never updated.

Not for this skill when

• The parameter is genuinely required and the integration is at fault.
• The API itself still requires the parameter - deprecate it in code first.
• You are designing the deprecation policy rather than fixing the docs.

Variant phrasings

deprecated param marked required in docs

Same contradiction, different word order. Same fix.

docs say required but api ignores the parameter

The user-visible symptom of the same drift. Same fix.

integration broken by deprecated required field

Same, reported from the client side. Same fix.

Why it happens

Deprecation ships as a code change (a flag flip, a warning log) while the "required" label lives in the spec or docstring that nobody updated. Generated docs faithfully reproduce the stale label, so the docs look authoritative while describing a contract the server no longer enforces.

Edge cases

• Both flags at once: some specs end up with deprecated: true AND required: true. Renderers show "required" and users obey it. Clear the required flag explicitly.
• Versioned docs: the parameter may be required in v1 docs and deprecated in v2. Make sure each version's source carries the right flags.
• SDKs generated from the same spec inherit the contradiction. Regenerate them after fixing the spec.

Provenance

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