API Documentation Generator from Endpoint Code
Why this prompt matters
API documentation debt compounds fast — endpoints shipped undocumented stay undocumented for months or years because no one wants to reverse-engineer them later. The typical cost: integration errors, support tickets, and delays every time a new developer touches that endpoint. This prompt eliminates the friction by making documentation the fastest part of shipping an endpoint, not an afterthought. The structured Role + Output Format approach is critical because without it, models produce prose summaries instead of the schema tables and curl examples that developers actually need for integration.
What we use it for
You have just finished writing a new API endpoint and need to hand it off to a frontend developer, a third-party integrator, or your own team. The endpoint has validation logic scattered across middleware and the controller, and writing the documentation by hand would take 30-45 minutes. This prompt lets you paste the code and get publish-ready documentation in under 30 seconds.
Prompt
Act as a senior API technical writer with deep expertise in REST API design and OpenAPI 3.0 documentation standards. Context: I have an API endpoint written in [FRAMEWORK] / [LANGUAGE] that needs complete, developer-ready documentation. The endpoint is part of [YOUR PROJECT NAME / DOMAIN]. Task: Analyze the following endpoint code and produce complete API documentation covering every detail a developer needs to integrate this endpoint correctly. ``` [PASTE YOUR FULL ENDPOINT HANDLER CODE HERE — include route definition, middleware, validation logic, controller/handler function, and error handling] ``` Constraints: - Do not omit any parameters you can infer from the code — if validation logic implies a constraint (e.g., minLength, required, enum values), include it - Do not guess at business logic that is not in the code — if something is unclear, mark it as [TO CLARIFY] - Keep all parameter names and field names exactly as they appear in the code - Use technical documentation vocabulary, not conversational descriptions Output Format — produce exactly these sections: ## Endpoint Overview - Method and path - Authentication requirement (inferred from middleware) - Rate limiting notes (if any) - Short description (1-2 sentences) ## Request Specification ### Path Parameters (table: name | type | required | description | constraints) ### Query Parameters (table: name | type | required | default | description | constraints) ### Request Body (table: field | type | required | description | validation rules) ## Response Specification ### Success Response (2xx) (schema with field names, types, example values) ### Error Responses (table: status code | error code | meaning | when it occurs | how to fix) ## Example Request ```bash curl [working example with realistic sample values matching all validation rules] ``` ## Example Response ```json [realistic JSON response matching the success schema] ```
<h2>What This Prompt Does</h2><p>Writing API documentation is one of the most time-consuming tasks in software development — and one of the most skipped. This prompt turns raw endpoint code into complete, developer-ready documentation: endpoint description, HTTP method, path parameters, query parameters, request body schema, response schema, status codes, error handling, and curl examples. All in one pass.</p><h2>The Prompt</h2><p>The full prompt is above. Here is what each section is doing and why it matters:</p><h3>Why the Role Instruction Works</h3><p>Telling the AI to act as a senior API technical writer with REST and OpenAPI 3.0 expertise is not just flavor — it activates a specific output mode. The model produces structured documentation with proper vocabulary ("path parameter", "request body", "response schema") rather than generic paragraphs about what the code does.</p><h3>Why You Must Include the Full Code Block</h3><p>Partial code or just the function signature produces incomplete docs. The prompt instructs you to paste the entire endpoint handler — including middleware, validation logic, and error handling — because that is where the real documentation lives. The model reads the validation rules and converts them directly into parameter constraints like <code>required: true</code>, <code>minLength: 3</code>, <code>type: string</code>.</p><h3>The Output Format Section</h3><p>Without explicit output format instructions, models will write prose documentation. This prompt specifies a structured breakdown: Endpoint Overview, Request specification, Response specification, Error codes table, and a curl example. This is the format that goes directly into a README, Notion doc, or Swagger file without reformatting.</p><h2>What the Example Output Looks Like</h2><p>For a POST /api/users/register endpoint, you get:</p><ul><li><strong>Endpoint overview:</strong> Method, path, auth requirement, rate limiting note</li><li><strong>Request body:</strong> JSON schema with field names, types, constraints, and whether each is required</li><li><strong>Response:</strong> 201 success schema, plus 400/409/422/500 error shapes</li><li><strong>Error table:</strong> Status code, error code string, meaning, and remediation hint</li><li><strong>curl example:</strong> A working command with realistic sample values</li></ul><h2>Best Used With</h2><p>This prompt works best with Claude 3.7 Sonnet or GPT-4o. Both handle code-to-documentation tasks reliably. For endpoints with complex validation logic (Joi, Zod, Pydantic), Claude tends to be more precise at extracting constraint rules. For OpenAPI YAML output specifically, GPT-4o produces cleaner formatting.</p><h2>Adapting It to Your Stack</h2><p>The <code>[FRAMEWORK]</code> and <code>[LANGUAGE]</code> fields matter. "Express.js / Node.js" produces JavaScript-native curl examples and uses Express middleware vocabulary. "FastAPI / Python" produces Python-style type annotations and recognizes Pydantic models. "Rails / Ruby" recognizes strong parameters and produces Rails-convention documentation. Always fill these in — they change the output quality significantly.</p>