أداة توليد توثيق واجهات API من كود الـ Endpoint
Why this prompt matters
API documentation debt compounds fast — endpoints shipped undocumented stay undocumented for months or years because no one wants to reverse-engineer them later. The typical cost: integration errors, support tickets, and delays every time a new developer touches that endpoint. This prompt eliminates the friction by making documentation the fastest part of shipping an endpoint, not an afterthought. The structured Role + Output Format approach is critical because without it, models produce prose summaries instead of the schema tables and curl examples that developers actually need for integration.
What we use it for
You have just finished writing a new API endpoint and need to hand it off to a frontend developer, a third-party integrator, or your own team. The endpoint has validation logic scattered across middleware and the controller, and writing the documentation by hand would take 30-45 minutes. This prompt lets you paste the code and get publish-ready documentation in under 30 seconds.
Prompt
Act as a senior API technical writer with deep expertise in REST API design and OpenAPI 3.0 documentation standards. Context: I have an API endpoint written in [FRAMEWORK] / [LANGUAGE] that needs complete, developer-ready documentation. The endpoint is part of [YOUR PROJECT NAME / DOMAIN]. Task: Analyze the following endpoint code and produce complete API documentation covering every detail a developer needs to integrate this endpoint correctly. ``` [PASTE YOUR FULL ENDPOINT HANDLER CODE HERE — include route definition, middleware, validation logic, controller/handler function, and error handling] ``` Constraints: - Do not omit any parameters you can infer from the code — if validation logic implies a constraint (e.g., minLength, required, enum values), include it - Do not guess at business logic that is not in the code — if something is unclear, mark it as [TO CLARIFY] - Keep all parameter names and field names exactly as they appear in the code - Use technical documentation vocabulary, not conversational descriptions Output Format — produce exactly these sections: ## Endpoint Overview - Method and path - Authentication requirement (inferred from middleware) - Rate limiting notes (if any) - Short description (1-2 sentences) ## Request Specification ### Path Parameters (table: name | type | required | description | constraints) ### Query Parameters (table: name | type | required | default | description | constraints) ### Request Body (table: field | type | required | description | validation rules) ## Response Specification ### Success Response (2xx) (schema with field names, types, example values) ### Error Responses (table: status code | error code | meaning | when it occurs | how to fix) ## Example Request ```bash curl [working example with realistic sample values matching all validation rules] ``` ## Example Response ```json [realistic JSON response matching the success schema] ```
ما الذي يفعله هذا الـ Prompt
كتابة توثيق API هي من أكثر المهام استهلاكاً للوقت في تطوير البرمجيات — وغالباً ما يتم تخطيها. هذا الـ Prompt يحوّل كود النقطة النهائية الخام إلى توثيق كامل جاهز للمطورين: وصف النقطة النهائية، طريقة HTTP، باراميترات المسار، باراميترات الاستعلام، مخطط جسم الطلب، مخطط الاستجابة، رموز الحالة، معالجة الأخطاء، وأمثلة curl. كل ذلك في تمريرة واحدة.
الـ Prompt
الـ Prompt الكامل موجود بالأعلى. إليك ما يفعله كل قسم ولماذا هو مهم:
لماذا يعمل تعيين الدور
إخبار الذكاء الاصطناعي بأن يعمل ككاتب تقني أول متخصص في REST و OpenAPI 3.0 ليس مجرد تزيين — بل ينشط نمط إخراج محدد. ينتج النموذج توثيقاً منظماً بمفردات صحيحة بدلاً من فقرات عامة تصف ما يفعله الكود.
لماذا يجب تضمين كتلة الكود الكاملة
الكود الجزئي أو مجرد توقيع الدالة ينتج توثيقاً غير مكتمل. يطلب الـ Prompt لصق معالج النقطة النهائية بالكامل — بما في ذلك الـ middleware ومنطق التحقق ومعالجة الأخطاء — لأن هناك يكمن التوثيق الحقيقي. يقرأ النموذج قواعد التحقق ويحوّلها مباشرة إلى قيود باراميترات مثل required: true و minLength: 3 و type: string.
قسم تنسيق الإخراج
بدون تعليمات صريحة لتنسيق الإخراج، ستكتب النماذج توثيقاً نثرياً. يحدد هذا الـ Prompt تفصيلاً منظماً: نظرة عامة على النقطة النهائية، مواصفات الطلب، مواصفات الاستجابة، جدول رموز الأخطاء، ومثال curl. هذا هو التنسيق الذي يذهب مباشرة إلى README أو مستند Notion أو ملف Swagger دون إعادة تنسيق.
كيف يبدو الإخراج النموذجي
لنقطة نهاية POST /api/users/register، تحصل على:
- نظرة عامة على النقطة النهائية: الطريقة، المسار، مصادقة مطلوبة، ملاحظة حول تحديد المعدل
- جسم الطلب: مخطط JSON بأسماء الحقول، الأنواع، القيود، وهل كل حقل مطلوب
- الاستجابة: مخطط النجاح 201، إضافة إلى أشكال الأخطاء 400/409/422/500
- جدول الأخطاء: رمز الحالة، سلسلة رمز الخطأ، المعنى، تلميح الإصلاح
- مثال curl: أمر جاهز بقيم نموذجية واقعية
أفضل استخدام مع
هذا الـ Prompt يعمل بشكل أفضل مع Claude 3.7 Sonnet أو GPT-4o. كلاهما يعالج مهام تحويل الكود إلى توثيق بشكل موثوق. للنقاط النهائية ذات منطق التحقق المعقد (Joi، Zod، Pydantic)، يميل Claude إلى الدقة الأكبر في استخراج قواعد القيود.
تكييفه مع بيئتك التقنية
حقل [FRAMEWORK] و [LANGUAGE] مهمان. "Express.js / Node.js" ينتج أمثلة curl بلغة JavaScript. "FastAPI / Python" ينتج تعليقات أنواع على نمط Python ويتعرف على نماذج Pydantic. املأ هذه الحقول دائماً — فهي تغير جودة الإخراج بشكل ملحوظ.