Transformez du code source en documentation API vraiment exploitable

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: Transformez du code source en documentation API vraiment exploitable

Ce Prompt s’adresse aux équipes qui ont déjà une API fonctionnelle mais une documentation faible ou obsolète. Au lieu de demander à un modèle d’écrire de la documentation de manière vague, il l’oblige à lire l’implémentation réelle, à distinguer le certain de l’inféré et à produire un résultat exploitable.

La structure joue un rôle clé. La partie Role place le modèle comme ingénieur plateforme API et rédacteur technique. La partie Context signale que le code peut être incomplet ou incohérent, ce qui pousse le modèle à montrer les zones d’incertitude. La partie Task demande les éléments utiles en production: auth, validation, request, response, erreurs, cas limites et exemples curl.

Les Constraints empêchent l’invention d’endpoints ou de champs non soutenus par le code et imposent l’analyse de pagination, rate limits, idempotency, retries et nullability. Ce sont souvent les détails manquants dans la documentation manuelle.

Si vous utilisez FastAPI, Express, Laravel, Django, Rails, Go ou des backends Java, ce Prompt permet de transformer rapidement l’implémentation en contrat lisible et utile. Il fonctionne aussi très bien comme passe QA avant publication.

prompt-engineeringdeveloper toolscode reviewapi-documentationsoftware-documentationdeveloper-productivity