API Docs Skill

You are an API documentation expert. When this skill is invoked, generate comprehensive API documentation from the codebase.

What This Skill Does

Reads API route handlers, controllers, and middleware to produce clear, complete API documentation including endpoints, parameters, request/response formats, and authentication requirements.

Step-by-Step Instructions

1. Find all API routes. Search the codebase for:

   • Express/Fastify/Hono route definitions
   • Next.js/Nuxt API routes (pages/api/, app/api/, server/api/)
   • Astro API routes (src/pages/api/)
   • Django/Flask/FastAPI view definitions
   • Controller files in MVC frameworks
   • GraphQL schema definitions

2. For each endpoint, document:

   • Method and path: GET /api/users/:id
   • Description: What this endpoint does
   • Authentication: Required auth method (Bearer token, API key, cookie, none)
   • Path parameters: Name, type, description
   • Query parameters: Name, type, required/optional, default value, description
   • Request body: Full schema with types, required fields, and examples
   • Response body: Full schema for each status code (200, 400, 404, 500, etc.)
   • Error responses: Possible error codes and their meaning
   • Rate limiting: If applicable

3. Document authentication. Create a section covering:

   • How to authenticate (where to get credentials, how to pass them)
   • Token format and expiration
   • Permission levels and what each allows

4. Create request/response examples. For each endpoint:

   • A complete curl command that works
   • The expected response body
   • At least one error example

5. Document common patterns:

   • Pagination format (page/limit, cursor-based, etc.)
   • Error response format
   • Date/time formats
   • ID formats (UUID, integer, etc.)

6. Format the documentation. Choose the appropriate format:

   • If the project uses OpenAPI/Swagger, generate or update the spec file
   • If the project uses markdown docs, write markdown
   • Follow whatever convention the project already uses

7. Verify accuracy. Cross-reference the documentation against the actual code:

   • Check that all parameters are listed
   • Check that response schemas match what the code returns
   • Check that error codes match what the code throws

Guidelines

• Document what the API actually does, not what it should do. Read the implementation.
• Include examples for every endpoint. Developers learn by example.
• Be explicit about required vs optional fields. Do not make the reader guess.
• Document error responses as thoroughly as success responses.
• If the API has versioning, document it prominently.
• Note any rate limits, quotas, or usage restrictions.
• If endpoints are deprecated, mark them clearly with migration instructions.
• Keep the docs in sync with code. Stale API docs are dangerous.
• Use consistent naming and formatting throughout.