REST API Design Review and Auto OpenAPI Docs with Claude Code

What to Review in an API

1. URL consistency (resource names, no verbs)
2. Correct HTTP methods (GET/POST/PUT/PATCH/DELETE)
3. Status codes (201 vs 200, 404 vs 400)
4. Error response format (consistent schema)
5. Pagination (cursor vs offset)
6. Versioning (/v1/, Accept-Version)

REST API Review Command

.claude/commands/api-review.md:

# REST API Review - $ARGUMENTS

## REST Principles
- URLs use nouns only
- Correct HTTP methods
- Max 2 nesting levels

## Status Codes
- GET: 200, 404
- POST: 201, 400
- DELETE: 204, 404

## Error Format (consistent)
{ "error": { "code": "...", "message": "...", "details": [] } }

List problems with fix suggestions.

Auto-Generate OpenAPI Docs

claude "Analyze src/routes/ Express routes.
Generate OpenAPI 3.0 YAML including:
- All endpoints with method/summary
- Request body schemas from TypeScript types
- Response schemas and error formats
- Auth requirements (Bearer token)
Output: docs/openapi.yaml"

Common Problems

// Bad
router.post('/getUser', h)              // verb in URL
router.get('/users/deleteUser/:id', h)  // use DELETE

// Good
router.get('/users/:id', h)
router.delete('/users/:id', h)
router.patch('/users/:id/status', h)

TypeScript to OpenAPI Schema

claude "Convert User interface from src/types/user.ts
to OpenAPI components/schemas YAML format."

Keep Docs Synced with Hooks

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "bash -c 'echo $CLAUDE_TOOL_INPUT | grep -q routes/ && echo REMINDER: Update docs/openapi.yaml || true'"
      }]
    }]
  }
}

Summary

API docs are most accurate right after writing code. Use Hooks to stay synced automatically.

---

This article is an excerpt from the Claude Code Complete Guide (7 chapters), available on note.com.
myouga (@myougatheaxo) - VTuber axolotl. Sharing practical AI development tips.