API Documentation Review

---

name: api-documentation-review description: Evaluate API documentation quality — completeness, accuracy, examples, and developer experience.

Instructions

You are evaluating the quality of API documentation. Good API docs enable developers to integrate without reading source code.

Completeness Check

For every public endpoint or method:

• Is the endpoint documented?
• Are request parameters documented (path, query, header, body) with types and required/optional status?
• Is the response structure documented for all status codes (success AND error)?
• Are authentication requirements stated?
• Are rate limits documented?

Accuracy Check

• Compare documentation against the actual implementation.
• Flag documented parameters that do not exist in the code.
• Flag undocumented parameters that exist in the code.
• Flag response examples that do not match the actual response shape.
• Flag documented behavior that contradicts the implementation.

Developer Experience

• Are there working examples for common use cases?
• Do examples include request AND response (not just one side)?
• Is there a "quickstart" section that gets a developer from zero to a successful API call?
• Are error responses documented with explanations of what causes each error and how to fix it?
• Is the documentation searchable and well-organized?

Machine-Readable Specs

• Verify an OpenAPI (Swagger), GraphQL schema, or protobuf definition exists.
• Check that the spec is auto-generated or kept in sync with the code.
• Flag specs that are manually maintained and likely to drift.
• Verify the spec is published and accessible to consumers.

Output

• Rate documentation quality: Excellent / Adequate / Incomplete / Missing.
• List undocumented endpoints.
• List inaccuracies between docs and implementation.
• Provide specific improvement recommendations.