GPT-5, Claude 4, or Gemini 2.5 Pro (best with long-context models that can read multiple files)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.Developer Tools

حوّل الشفرة المصدرية إلى مستندات API يمكن لفريقك استخدامها

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: حوّل الشفرة المصدرية إلى مستندات API يمكن لفريقك استخدامها

هذا Prompt مناسب للفرق التي تملك API يعمل فعلاً لكن مستنداته ضعيفة أو قديمة. بدلاً من طلب كتابة مستندات بشكل عام، فإنه يدفع النموذج إلى قراءة التنفيذ الحقيقي، وفصل السلوك المؤكد عن الاستنتاج، وإنتاج مادة يمكن للفريق التقني الاعتماد عليها.

البنية هنا مهمة. قسم Role يضع النموذج في دور مهندس منصة API وكاتب تقني معاً. قسم Context يوضح أن الشفرة قد تكون ناقصة أو غير متناسقة، لذلك يجب إظهار الغموض بدلاً من اختراع تفاصيل. أما قسم Task فيطلب العناصر التي تهم في العمل الفعلي: auth وvalidation وبنية request وresponse والأخطاء والحالات الطرفية وأمثلة curl.

قسم Constraints هو ما يجعل هذا Prompt عملياً. فهو يمنع اختراع endpoints أو حقول غير مدعومة، ويطلب تمييز المناطق الغامضة بوضوح، والتنبيه إلى pagination وrate limits وidempotency وretries وnullability. هذه غالباً هي التفاصيل التي تغيب عن المستندات اليدوية.

إذا كنت تعمل مع FastAPI أو Express أو Laravel أو Django أو Rails أو Go أو backends في Java، فهذا Prompt طريقة سريعة لتحويل التنفيذ إلى عقد واضح وقابل للاستخدام. كما أنه مفيد كخطوة QA قبل النشر لأنه يكشف أسماء حقول غير متسقة وأكواد أخطاء غير موثقة.

prompt-engineeringdeveloper toolscode reviewapi-documentationsoftware-documentationdeveloper-productivity