Transforme código-fonte em documentação de API que a equipe usa

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: Transforme código-fonte em documentação de API que a equipe usa

Este Prompt foi feito para equipes que já têm uma API funcionando, mas convivem com documentação fraca ou desatualizada. Em vez de pedir que a IA escreva documentação de forma genérica, ele força a leitura da implementação real, separa comportamento confirmado de inferência e gera algo útil para o time técnico.

A estrutura faz diferença. A seção Role posiciona o modelo como engenheiro de plataforma API e redator técnico ao mesmo tempo. A seção Context lembra que o código pode estar incompleto ou inconsistente, então o modelo precisa destacar incertezas. Em Task aparecem os pontos que importam no uso real: auth, validation, request, response, erros, edge cases e exemplos em curl.

As Constraints evitam endpoints ou campos inventados e pedem atenção a pagination, rate limits, idempotency, retries e nullability. São justamente os detalhes que costumam faltar na documentação manual.

Se você trabalha com FastAPI, Express, Laravel, Django, Rails, Go ou backends em Java, este Prompt acelera a transformação da implementação em contrato utilizável. Também funciona bem como revisão de QA antes da publicação.

prompt-engineeringdeveloper toolscode reviewapi-documentationsoftware-documentationdeveloper-productivity