يمكن للمهندسين توليد توثيق API مباشرة من كود الـ endpoint
Why this prompt matters
Engineering teams often ship endpoints faster than they document them, which leaves frontend developers, partners, QA, and new teammates relying on source code to understand basic usage. A strong prompt closes that gap by turning controllers, routes, schemas, and middleware into a consistent documentation draft. That speeds up integration, reduces support questions, and makes undocumented edge cases like auth rules or validation failures visible before they cause avoidable bugs.
What we use it for
Turning endpoint implementations into reusable API documentation with parameters, authentication requirements, validation rules, error cases, and copy-pasteable curl examples.
Prompt
Act as a senior API technical writer and backend engineer. I will paste endpoint code, controller logic, route definitions, request and response schemas, validators, auth middleware, error handling, comments, and sometimes tests. Your job is to convert that implementation detail into clean, developer-facing API documentation that another engineer could use without reading the source code. Return your answer in exactly these sections: 1. Endpoint Summary 2. HTTP Method and Path 3. What This Endpoint Does 4. Authentication Requirements 5. Request Headers 6. Path Parameters 7. Query Parameters 8. Request Body Schema 9. Validation Rules and Constraints 10. Success Response 11. Error Responses 12. Example cURL Request 13. Example Success Response JSON 14. Implementation Notes and Assumptions Rules: - Base the documentation only on the code and context provided. Do not invent fields, permissions, business rules, or status codes that are not supported by the source. - If something is implied but not fully certain, place it under Implementation Notes and Assumptions. - Normalize naming so the final documentation is easy to read, but preserve exact parameter names, enum values, header names, and route paths. - If auth middleware is present, explain the auth mechanism plainly, including required header format when visible in the code. - If validation logic exists, convert it into practical parameter constraints such as required, optional, type, format, min or max, allowed values, and defaults. - If the code shows multiple failure paths, list each distinct error with status code, trigger, and response shape when available. - If the endpoint interacts with pagination, filtering, sorting, idempotency, rate limits, or tenant scoping, include those details when explicitly present. - Write for engineers who need usable docs fast, not a marketing description. - Keep the output concise but implementation-ready. Source code and related context: [PASTE CODE HERE]
Result
غالباً ما يتأخر توثيق واجهات API عن الكود الذي يتم شحنه فعلاً. يضيف فريق الخلفية مساراً جديداً، أو يحدّث التحقق، أو يغيّر شرط المصادقة، أو يضيف مسار خطأ جديداً، بينما تبقى الوثائق ناقصة أو قديمة. والنتيجة معروفة داخل الفرق الهندسية: يضطر الناس إلى قراءة الـ controllers والمخططات والـ middleware فقط لفهم أسئلة تكامل أساسية.
هذا الموجه صُمم لتحويل هذه التفاصيل التنفيذية إلى توثيق قابل للاستخدام بسرعة. بدلاً من طلب ملخص عام، فهو يفرض بنية واضحة: ملخص الـ endpoint، الطريقة والمسار، المصادقة، الرؤوس، المعلمات، مخطط الطلب، قواعد التحقق، الاستجابة الناجحة، استجابات الخطأ، ومثال cURL. هذه البنية مهمة لأنها تطابق الأسئلة التي يحتاج مطورو الواجهة الأمامية ومهندسو QA ومهندسو الشركاء والكتّاب التقنيون إلى إجابات عنها عادة.
كما أن هذا الموجه يقلل خطر الهلوسة لأنه يطلب من النموذج أن يبقى ملتزماً بالكود المقدم وأن ينقل النقاط غير المؤكدة إلى قسم الافتراضات. وهذا مهم جداً في عمل API، لأن اختراع حقل أو رمز حالة يجعل الناتج أسوأ من غير مفيد. وعبر فصل المعلومات المؤكدة عن الملاحظات المستنتجة، يصبح الناتج أكثر عملية وأكثر أماناً لإعادة الاستخدام.
ومن أسباب نجاح هذا الموجه أيضاً أنه يترجم أنماط الكود منخفضة المستوى إلى لغة موجّهة للمطورين. تتحول الـ middleware إلى شرح واضح لمتطلبات المصادقة. وتتحول قواعد التحقق إلى قيود سهلة القراءة على المعلمات. وتتحول فروع الأخطاء إلى حالات فشل موثقة مع رموز الحالة وأسبابها المحتملة. كما تصبح الاختبارات وتعريفات المسارات أدلة داعمة للأمثلة والسلوك.
وعند استخدامه جيداً، يمكن لهذا الموجه أن يساعد الفرق على بناء التوثيق الداخلي بسرعة أكبر، وتحسين التسليم بين فرق الخلفية والواجهة الأمامية، وإنشاء مسودة أولى أنظف لمراجع API الخارجية من دون البدء من صفحة فارغة.