Convierte código fuente en documentación API que tu equipo sí usará

April 22, 2026

Why this prompt matters

Bad API docs slow integration, create support tickets, and turn simple launches into guesswork. A strong prompt helps teams extract the contract from real code, catch missing edge cases early, and ship cleaner developer experience without starting from a blank page.

What we use it for

Use this when you have working API code but weak or outdated documentation, especially before handing an endpoint to frontend engineers, partners, QA teams, or external developers.

Prompt

Role: Act as a senior API platform engineer and technical writer.

Context: I will give you source code, route definitions, validators, example payloads, and any notes I have. The code may be incomplete, inconsistent, or lightly documented. Your job is to infer the real API contract from the implementation without inventing behavior that is not supported by the code.

Task: Produce complete API documentation for [API NAME] based on the code and notes I provide. Document each endpoint with: purpose, HTTP method, path, authentication requirements, request headers, path/query/body parameters, validation rules, request example, success response example, error responses, important edge cases, and one curl example. If the API behavior is ambiguous, explicitly label the uncertainty and list the exact code area that needs human review.

Inputs:
- Product/service name: [API NAME]
- Intended audience: [INTERNAL DEVELOPERS | PARTNERS | PUBLIC DEVELOPERS]
- Source code or route files: [PASTE CODE OR FILE CONTENTS]
- Validation schemas / types: [PASTE SCHEMAS]
- Auth details: [PASTE AUTH LOGIC OR NOTES]
- Known business rules: [PASTE NOTES]

Constraints:
1. Do not invent endpoints, fields, or response codes that are not supported by the inputs.
2. Separate confirmed behavior from inferred behavior.
3. Use plain English and keep jargon low unless the code requires it.
4. Include warnings for breaking changes, unsafe defaults, or inconsistent naming.
5. If examples are missing, generate clearly labeled illustrative examples that match the schema.
6. Call out undocumented pagination, rate limits, idempotency behavior, retries, and nullability when visible in code.
7. End with a short section titled "Gaps to confirm with engineering".

Output Format:
Return the result in this exact structure:
1. API overview
2. Authentication
3. Base URL and versioning
4. Endpoint reference (repeat per endpoint)
5. Error model
6. Common workflows
7. Breaking-change and quality risks
8. Gaps to confirm with engineering

Result

API Overview The Orders API lets internal commerce systems create, retrieve, update, and cancel customer orders. It uses token-based authentication and returns JSON for all endpoints. Based on the controller and validation schema, the API currently exposes four stable endpoints under /v1/orders. Authentication All routes require an Authorization header in the format Bearer . The middleware checks for the token before route execution and returns 401 when missing or invalid. I do not see role-based authorization in the provided code, so access appears to be authenticated but not scope-restricted. Endpoint Reference POST /v1/orders Purpose: Create a new order record. Request body: - customerId (string, required) - items (array, required, minimum 1 item) - currency (string, required, 3-character code) - notes (string, optional, nullable) Validation notes: The schema rejects empty item arrays and negative quantities. Success response: 201 Created with orderId, status, createdAt, and normalized line items. Possible errors: 400 for validation failure, 401 for missing token, 409 when clientOrderId already exists. Curl example: curl -X POST https://api.example.com/v1/orders -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' -d '{"customerId":"cust_128","items":[{"sku":"kb-104","quantity":2}],"currency":"USD"}' GET /v1/orders/:orderId Purpose: Fetch one order by ID. Path params: orderId (string, required). Success response: 200 OK with order object. Possible errors: 401 unauthorized, 404 not found. Breaking-change and quality risks The code uses both created_at and createdAt in different layers, which could confuse SDK generation and clients. Error payloads are also inconsistent between the create and cancel handlers. Gaps to confirm with engineering 1. Whether rate limits exist at the gateway level. 2. Whether idempotency is required for order creation. 3. Whether cancelled orders can be updated afterward. 4. Whether partner clients should see the same error detail as internal clients.

Generated Image

Output for: Convierte código fuente en documentación API que tu equipo sí usará

Este Prompt sirve para equipos que ya tienen una API funcionando pero una documentación débil o desactualizada. En lugar de pedirle a la IA que escriba documentación de forma genérica, la obliga a leer la implementación real, separar comportamiento confirmado de inferencias y producir algo útil para el equipo técnico.

La estructura importa. La sección Role coloca al modelo como ingeniero de plataforma API y redactor técnico al mismo tiempo. La sección Context deja claro que el código puede estar incompleto o ser inconsistente, así que el modelo debe señalar incertidumbres. En Task aparecen los elementos que realmente importan: auth, validation, request, response, errores, casos límite y ejemplos con curl.

Las Constraints hacen que el Prompt sea reutilizable. Le impiden inventar endpoints o campos no respaldados por la entrada y le exigen detectar pagination, rate limits, idempotency, retries y nullability. Justo ahí suelen estar los vacíos de la documentación manual.

Si trabajas con FastAPI, Express, Laravel, Django, Rails, Go o backends en Java, este Prompt acelera el paso de implementación a contrato usable. También funciona muy bien como revisión de QA antes de publicar documentación.

prompt-engineeringdeveloper toolscode reviewapi-documentationsoftware-documentationdeveloper-productivity