api-content-type-doctor

A tiny zero-dependency CLI that grades API documentation for Content-Type, Accept, and media negotiation. It catches the boring-but-costly gaps that cause integrations to fail with mysterious 400, 406, or 415 errors.

Why people use it

Great API docs should make these obvious:

• Which endpoints require application/json?
• Does the API support multipart/form-data uploads?
• Is charset=utf-8 required?
• What happens when Content-Type is missing or wrong?
• Which Accept headers are supported?
• Where are 415 and 406 errors documented?

api-content-type-doctor turns those questions into a repeatable score.

Run

npx api-content-type-doctor docs/media-types.md
npx api-content-type-doctor README.md --min-score 90
npx api-content-type-doctor docs/media-types.md --json

No dependencies. Node.js 18+.

What it checks

• Request Content-Type documentation
• Response Accept / content negotiation behavior
• JSON body rules, UTF-8 charset, malformed JSON behavior
• application/x-www-form-urlencoded rules
• multipart/form-data upload rules, boundaries, filenames, MIME handling
• Charset and encoding support
• 415 unsupported_media_type error examples
• 406 not_acceptable behavior
• Concrete curl examples with headers
• Endpoint media type matrix
• Upload security, MIME sniffing, malware scanning, and size limits
• Vendor media types and versioning
• OpenAPI requestBody.content / responses.content alignment

CLI

api-content-type-doctor <README.md|docs.md> [--min-score 80] [--json] [--expect-fail]

Exit codes:

• 0 passes the minimum score
• 1 fails the minimum score
• 2 invalid CLI usage or unreadable file

Development

npm test
npm run check

License

MIT