The worked example identifies four differences between a revised supply API description and an older documentation record: the title, declared item fields, required item fields, and response example. Its editable comparison helps you locate the mismatch. It is a local review aid, not a native documentation generator or proof that a build ran.
Use a response small enough to inspect
The fictional Practice Supply API uses OpenAPI 3.0.3 and one operation: GET /supplies, with operation ID listSupplies. Its 200 response has description Supplies listed and media type application/json. The response is an object requiring items, an array of objects. Each object requires two string fields, id and label.
The S1 example response is {"items":[{"id":"s1","label":"Brush"}]}. In S2, change the title to Practice Supply API revised and rename label to displayLabel in three places: the item object's property declaration, its required list, and the response example. Keep id, items, and Brush unchanged. The example provides both complete descriptions as editable JSON, so you can inspect the enclosing structure without reconstructing it from fragments.
OpenAPI's media-type record holds the schema and example. The schema keyword items describes an array element; the payload property named items contains the actual list. Keep those two uses separate when following the response structure. OpenAPI 3.0.3 specification
Generate the native reference
For a maintained file named openapi.yaml, the documented starting command is redocly build-docs openapi.yaml. Its default output filename is redoc-static.html. Check the installed CLI version and command help before running it in your project. Redocly build-docs documentation
Before generation, record the source revision, exact source-byte fingerprint, working directory, configuration, and generator/runtime versions. Afterward, retain the exact command, start and end times, exit result, output path, and artifact-byte fingerprint. Source and artifact fingerprints identify different files; they should not be compared for equality. Keep the API's info.version separate from both the generator version and source revision.
Preserve the last inspected artifact before another build. After a failed command, treat any remaining output file as unverified. An existing filename alone cannot establish a successful replacement. Keep the new candidate separate until you have checked its run record and rendered contents.
Work through the stale-page comparison
Open the example with S1 selected. Its illustrative S1 observation record agrees with all four comparisons. Choose Use S2 source, then Compare records. The result changes to 4 of 4 checks differ. The source expects displayLabel, while the old observation still records label; the revised title differs too.
Choose Load S2 observation, then Compare records, to compare matching sample records. This changes the local comparison, without executing a CLI. For your own inspection, replace the observation JSON with values you actually read from the generated reference. The tool compares this one response shape, not arbitrary OpenAPI documents or unresolved references.
The record also distinguishes a pending build, a failed build, and generated output awaiting inspection. Matching fields cannot clear those states. Agreement between recorded values is only one part of verification. Check the operation, response code, media type, and s1/Brush example in the actual rendered reference, and record how you reached them. Do not assume the generator displays operation IDs or navigation anchors in a particular way.
Reproduce the comparison aid
Create one responsive, self-contained HTML review tool for a developer checking stale OpenAPI documentation. This is a manually recorded comparison aid, not Redoc, a CLI execution, or a generated-reference audit. Label all presets illustrative. Use no remote assets, backend, downloads, or persistence.
Provide complete editable OpenAPI 3.0.3 JSON for S1: info title Practice Supply API, version 1.0.0; GET /supplies, operationId listSupplies; response 200 description Supplies listed, application/json. Its schema is an object requiring items, an array of objects requiring id and label, both strings. Its media-type example is {"items":[{"id":"s1","label":"Brush"}]}. Add no server, authentication, or live API.
S2 changes the title to Practice Supply API revised and renames label to displayLabel in properties, required, and example. Preserve everything else. Add source preset buttons and an editable observation JSON with title, fields, required, example, and runStatus. Include S1/S2 observation presets, a failed-run preset, and reset.
Compare the title, item property names and types, required names, and JSON example. Show expected and recorded values for each of four checks. S1 matches its observation; S2 against S1 differs on all four. Compare object keys without depending on their order. Reject malformed JSON and unsupported source shapes with useful messages. Handle pending, failed, and uninspected run states separately from field agreement. Every input change invalidates the previous result.
Use explicit type=button click handlers, labeled textareas, visible keyboard focus, a live result region, at least 16px text, and a stacked layout at 360px. Use a restrained technical notebook design. Keep native build metadata pending and explain the actual build ledger requirements below the comparison. Return only the HTML.
After the real S2 build, inspect the revised title, schema, and example before attaching that artifact to its source revision. Check its asset references and hosting requirements separately. Linting, HTML generation, rendered inspection, and live API testing answer different questions; this fictional API supplies no live service to test.
Keep an optional reading copy in NOS
If a teammate needs an HTML explanation of the rename, prepare that reading copy after the native checks. In NOS, eligible static explanatory text can be revised in visual editing mode without asking AI to regenerate the HTML. Use that for clarifying the migration note, while keeping the maintained OpenAPI file and build record authoritative.