تولیدکننده مستندات 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 را به سرویس صورتحساب تیم شما اضافه میکند. اندپوینت کار میکند، تستها موفق هستند، اما هیچکس مستندات ننوشته است — و مدیر تیم شما همین الان از شما خواسته مستندات را قبل از اینکه شرکای خارجی هفته آینده شروع به فراخوانی آن کنند، در پورتال توسعهدهنده قرار دهید. کد جلوی روی شماست و چهلوپنج دقیقه تا جلسه بعدیتان وقت دارید.
چرا اهمیت دارد
APIهای داخلی مستندنشده یک مالیات قابلپیشبینی روی زمان مهندسی ایجاد میکنند: همان چند سؤال هر بار که کسی جدید سعی میکند یکپارچهسازی کند در اسلک پرسیده میشود — نام هدر احراز هویت چیست، آیا این فیلد اجباری است، ۴۲۲ اینجا واقعاً چه معنایی دارد — و هر رشته گفتگو زمان تمرکز واقعی مهندس پاسخدهنده را میگیرد که هرگز پس نمیگیرد. بدتر از آن، وقتی اندپوینتهای روبهشریک بدون پاسخهای خطای مستندشده منتشر میشوند، باگهای یکپارچهسازی به یک کد وضعیت نادرستفهمیدهشده بهجای یک فیلد نادرستخواندهشده ردیابی میشوند، و به تیکتهای پشتیبانی تبدیل میشوند که یک گذر پنجدقیقهای نوشتن مستندات کاملاً از آن جلوگیری میکرد.