THE GITHTML FIELD GUIDE
Verify AI-generated API documentation against the actual contract
Review AI-generated API documentation operation by operation. Confirm that the endpoint exists, the method and parameters match the contract, and the response and error examples reflect supported behavior. Pay particular attention to defaults and authorization, where a plausible explanation can mislead readers into using the API incorrectly.
Establish the authoritative API version
Identify the contract file, implementation revision, and supported API version before reviewing the prose. A generated page may combine details from several versions into a coherent but nonexistent interface. OpenAPI provides a structured description of operations and schemas; compare the draft with the version your project actually uses. If the implementation and published contract disagree, record that discrepancy rather than choosing whichever source matches the draft. The review should expose the disagreement for the responsible team, not conceal it through smoother wording.
Inspect one request all the way through
For an illustrative export operation, verify its route, required identifier, accepted content type, authentication requirement, and successful response. Then inspect an invalid identifier, an unauthorized request, and a pending result. These examples are fictional review cases, not claims about a specific service. Check whether omitted parameters use a default or cause an error, whether a field can be null, and whether pagination is involved. Generated examples often look internally consistent even when they use the wrong field name; consistency within the draft is not external evidence.
- Existence: locate the operation and parameter in the declared contract.
- Behavior: verify conditions, defaults, and important errors against source or tests.
- Example: use synthetic values and label unexecuted requests as illustrative.
Resolve mismatches before formatting
Keep a discrepancy list with the draft claim, conflicting evidence, and required owner decision. Do not silently change the contract or code as part of a documentation review. If a request example was executed in an approved environment, record that fact separately from merely inspecting it. Publish only claims supported for the intended version. In the final HTML, keep code escaped and readable; do not add a live API console to make a reference page feel complete. gitHtml displays the document and is not an API testing tool.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.