---
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.