مولد وثائق API: حوّل شيفرة نقطة نهاية غير موثقة إلى وثائق جاهزة للنشر
لماذا تهم هذه المطالبة
Undocumented internal APIs generate a predictable tax on engineering time: the same few questions get asked in Slack every time someone new tries to integrate — what's the auth header called, is this field required, what does a 422 actually mean here — and each thread costs the answering engineer real focus time they don't get back. Worse, when partner-facing endpoints ship without documented error responses, integration bugs get traced back to a misunderstood status code instead of a misread field, turning into support tickets that a five-minute doc-writing pass would have prevented entirely.
فيم نستخدمها
You just merged a pull request that adds a new POST /api/v1/refunds endpoint to your team's billing service. The endpoint works, tests pass, but nobody wrote documentation — and your team lead just asked you to get docs into the developer portal before external partners can start calling it next week. You have the code in front of you and forty-five minutes before your next meeting.
المطالبة
Act as a senior API technical writer who has documented REST APIs for developer platforms used by thousands of external engineers.
Context — here is what I'm working with:
- I'm going to paste the source code for [NUMBER OF ENDPOINTS] API endpoint(s), written in [LANGUAGE/FRAMEWORK, E.G. EXPRESS.JS, FASTAPI, SPRING BOOT]. The code includes the route handler, any middleware, and validation logic.
- [OPTIONAL: PASTE AN EXISTING DOC PAGE OR STYLE GUIDE HERE FOR TONE/FORMAT CONSISTENCY]
Code to document:
[PASTE YOUR ENDPOINT CODE HERE]
Task: Do this in two passes.
Pass 1 — Extract the contract: Read the code and infer, strictly from what's actually there, the HTTP method and path, the authentication requirement, every path/query/body parameter with its type and whether it's required, the success response shape and status code, and every error condition the code actually handles with its status code and message.
Pass 2 — Write the documentation: Using only what you extracted in Pass 1, produce publish-ready API documentation.
Constraints:
- Do not invent, assume, or infer any parameter, behavior, rate limit, or error case that isn't evidenced in the code itself.
- If something is ambiguous or the code doesn't make a behavior clear (e.g., what happens if an optional field is malformed), flag it under a "Needs Clarification" section instead of guessing.
- No marketing language ("powerful", "seamless", "easy to use") — this is reference documentation, not a landing page.
- Use standard HTTP status code conventions unless the code deviates from them, in which case document the actual deviation.
- Every example must be a working, copy-pasteable example, not a placeholder like "..." where a real value should be.
Output format (Markdown):
1. Endpoint summary — one line: what this endpoint does
2. Authentication — what's required, referencing the actual auth mechanism in the code
3. Request — method + full path; path parameters table (name, type, required, description); query parameters table; request body schema (if applicable) with types and required/optional
4. Response — success: status code + example JSON response; errors: table of status code, error condition, example error response
5. Example request — a working curl command with realistic (not placeholder) values
6. Needs Clarification — bullet list of anything ambiguous in the source code (omit this section entirely if nothing is ambiguous)النتيجة
Endpoint summary
Processes a full or partial refund for a completed payment.
Authentication
Requires a bearer token with the payments:write scope, passed in the Authorization header. Requests without this scope return a 403.
RequestPOST /api/v1/refunds
Request body:
payment_id(string, required) — the ID of the original payment to refundamount_cents(integer, optional) — amount to refund in cents; if omitted, the full remaining payment amount is refundedreason(string, optional) — one ofduplicate,fraudulent,requested_by_customer; defaults torequested_by_customerif omitted
Response
Success (200):
{
"refund_id": "rf_8h2j9k",
"payment_id": "pay_4f5e6d",
"amount_cents": 2500,
"status": "succeeded",
"created_at": "2026-08-10T09:12:00Z"
}Errors:
404—payment_iddoes not match an existing payment409— refund amount exceeds the remaining refundable balance on the payment422—amount_centsis present but not a positive integer
Example request
curl -X POST https://api.example.com/v1/refunds \
-H "Authorization: Bearer sk_live_51H..." \
-H "Content-Type: application/json" \
-d '{"payment_id": "pay_4f5e6d", "amount_cents": 2500, "reason": "requested_by_customer"}'Needs Clarification
- The code does not specify what happens if a refund is requested on a payment that has already been fully refunded — worth confirming with the endpoint's author before this ships to partners.
موجّه بمرحلتين يقرأ شيفرة نقطة النهاية الخاصة بك، يستخرج العقد الفعلي، ويكتب وثائق مرجعية تشير إلى الغموض بدلاً من التخمين — مصمم لسد الفجوة بين «الشيفرة تعمل» و«الوثائق منشورة».
حالة الاستخدام
لقد دمجت للتو طلب سحب يضيف نقطة نهاية جديدة POST /api/v1/refunds إلى خدمة الفوترة الخاصة بفريقك. نقطة النهاية تعمل، والاختبارات ناجحة، لكن لم يكتب أحد الوثائق — وطلب منك قائد فريقك للتو إدراج الوثائق في بوابة المطورين قبل أن يبدأ الشركاء الخارجيون باستدعائها الأسبوع القادم. الشيفرة أمامك ولديك خمس وأربعون دقيقة قبل اجتماعك التالي.
لماذا يهم
تولّد واجهات برمجة التطبيقات الداخلية غير الموثقة ضريبة يمكن التنبؤ بها على وقت الهندسة: تُطرح نفس الأسئلة القليلة في سلاك في كل مرة يحاول فيها شخص جديد الدمج — ما اسم رأس المصادقة، هل هذا الحقل مطلوب، ماذا يعني 422 فعلياً هنا — وتكلف كل محادثة المهندس المجيب وقت تركيز حقيقي لا يستعيده أبداً. والأسوأ من ذلك، عندما تُشحن نقاط النهاية الموجهة للشركاء دون استجابات خطأ موثقة، تُتتبع أخطاء التكامل إلى رمز حالة أُسيء فهمه بدلاً من حقل أُسيئت قراءته، وتتحول إلى تذاكر دعم كان يمكن لمرور خمس دقائق من كتابة الوثائق منعها تماماً.