中文
devexamples
← Workflows

阅读中文版本

API Doc Drift Check

Keep documentation accurate: check API docs against the live spec, audit runbook freshness, and fix drift before it misleads.

intermediate~25 mindocsqualityapi

Objective

Eliminate documentation drift so every public API and runbook matches the current system behavior.

Environment

  • A working docs environment with access to the target system and its tooling
  • Configuration and credentials for the docs workflow installed and verified
  • A rollback or undo path documented before any change is applied

Steps

1. Check API doc drift

Diff the generated API spec against the documented examples and flag any endpoint, parameter, or status code that changed.

Expected state: A drift report lists every mismatch with the current spec.

2. Audit runbook freshness

List runbooks by last-updated date and flag any that reference retired alerts or removed commands.

Expected state: Stale runbooks are identified and assigned for update.

3. Fix and verify

Update the drifted sections, regenerate examples from the live spec, and confirm the docs build passes.

Expected state: Docs match the live system and the build is green.

Decision points

Should docs be generated or hand-written?

  • Generate reference from spec, hand-write guides
  • Hand-write everything for tone

Generate reference docs from the spec for accuracy and hand-write guides for tone and context.

Expected outcome

Eliminate documentation drift so every public API and runbook matches the current system behavior. The change is verified and a rollback path is confirmed.

Verification

Eliminate documentation drift so every public API and runbook matches the current system behavior. Compare before and after metrics and confirm the expected state is reached.

Cleanup

Archive the run artifacts, remove temporary credentials, and update the runbook with any changes.

Overview

Keep documentation accurate: check API docs against the live spec, audit runbook freshness, and fix drift before it misleads. The goal is to eliminate documentation drift so every public api and runbook matches the current system behavior.

redocly lint openapi.yaml --skip-rule security-defined

Steps

  1. Check API doc drift. Diff the generated API spec against the documented examples and flag any endpoint, parameter, or status code that changed. Expected: A drift report lists every mismatch with the current spec.

  2. Audit runbook freshness. List runbooks by last-updated date and flag any that reference retired alerts or removed commands. Expected: Stale runbooks are identified and assigned for update.

  3. Fix and verify. Update the drifted sections, regenerate examples from the live spec, and confirm the docs build passes. Expected: Docs match the live system and the build is green.

Verification

Confirm the outcome by checking: eliminate documentation drift so every public api and runbook matches the current system behavior. Run the verification command and compare the result against the expected state. If any check fails, stop and investigate before continuing.

Decision points

  • Should docs be generated or hand-written?
    • Generate reference from spec, hand-write guides
    • Hand-write everything for tone
    • Recommendation: Generate reference docs from the spec for accuracy and hand-write guides for tone and context.