تولید خودکار مستندات 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] ```
این پرامپت چه کاری انجام میدهد
نوشتن مستندات API یکی از زمانبرترین کارهای توسعه نرمافزار است—و معمولاً اولین چیزی که از آن صرفنظر میشود. این پرامپت کد خام Endpoint را به مستندات کامل و آماده برای توسعهدهنده تبدیل میکند: توضیحات Endpoint، متد HTTP، پارامترهای مسیر، پارامترهای query، اسکیما بدنه درخواست، اسکیما پاسخ، کدهای وضعیت، مدیریت خطا و مثالهای curl. همه در یک مرحله.
پرامپت
پرامپت کامل در بالا آورده شده است. در ادامه توضیح میدهیم هر بخش چه کاری انجام میدهد و چرا مهم است.
چرا دستور نقش (Role Instruction) کار میکند
گفتن به هوش مصنوعی که بهعنوان یک نویسنده فنی ارشد API با تخصص REST و OpenAPI 3.0 عمل کند فقط یک حرف اضافه نیست—بلکه حالت خروجی خاصی را فعال میکند. مدل مستندات ساختاریافته با واژگان مناسب تولید میکند، نه پاراگرافهای کلی درباره کاری که کد انجام میدهد.
چرا باید کل بلاک کد را بگذارید
کد ناقص یا فقط امضای تابع مستندات ناقصی تولید میکند. پرامپت به شما میگوید که کل هندلر Endpoint را بچسبانید—شامل middleware، منطق اعتبارسنجی و مدیریت خطا—چون اطلاعات واقعی مستندات در همین جاهاست. مدل قوانین اعتبارسنجی را میخواند و مستقیماً به محدودیتهای پارامتر تبدیل میکند، مثلاً required: true، minLength: 3، type: string.
بخش فرمت خروجی
بدون دستورالعمل صریح برای فرمت خروجی، مدلها مستندات توصیفی مینویسند. این پرامپت یک تفکیک ساختاریافته مشخص میکند: نمای کلی Endpoint، مشخصات درخواست، مشخصات پاسخ، جدول کدهای خطا و یک مثال curl. این فرمتی است که مستقیماً بدون نیاز به قالببندی مجدد به یک README، Notion یا فایل Swagger میرود.
خروجی نمونه چه شکلی است
برای Endpoint POST /api/users/register، خروجی به این صورت است:
- نمای کلی Endpoint: متد، مسیر، نیاز به احراز هویت، نکته محدودیت نرخ
- بدنه درخواست: اسکیما JSON با نام فیلدها، انواع، محدودیتها و الزامی بودن هر کدام
- پاسخ: اسکیما موفقیت 201، به علاوه شکل خطاهای 400/409/422/500
- جدول خطا: کد وضعیت، رشته کد خطا، معنی و راهنمای رفع
- مثال curl: یک دستور کاربردی با مقادیر نمونه واقعی
بهترین استفاده با
این پرامپت بیشتر با Claude 3.7 Sonnet یا GPT-4o جواب میدهد. هر دو کار تبدیل کد به مستندات را قابلاعتماد انجام میدهند. برای Endpointهایی با منطق اعتبارسنجی پیچیده (Joi, Zod, Pydantic)، کلود معمولاً در استخراج قوانین محدودیت دقیقتر است.
سفارشیسازی برای استک خود
فیلدهای [FRAMEWORK] و [LANGUAGE] مهم هستند. "Express.js / Node.js" مثالهای curl بومی جاوااسکریپت تولید میکند. "FastAPI / Python" حاشیهنویسی نوع به سبک پایتون تولید میکند و مدلهای Pydantic را تشخیص میدهد. همیشه این فیلدها را پر کنید—کیفیت خروجی را به طور قابل توجهی تغییر میدهند.