هذا Prompt يحول كود endpoint إلى وثائق API جاهزة للنشر
Why this prompt matters
Undocumented endpoints slow down every team that touches them. Engineers waste time reading handlers, support teams answer the same integration questions repeatedly, and partner launches slip because nobody is fully sure which fields are required or what errors to expect. A prompt like this turns documentation from an afterthought into a release artifact.
What we use it for
Use this prompt when you are shipping or reviewing an API endpoint and the docs are lagging behind the code. It is especially useful when a backend engineer needs to turn a route handler, schema, and a few response examples into publishable docs before a release, SDK handoff, or partner integration.
Prompt
Role: Act as a senior API technical writer and backend engineer who documents production endpoints for developer platforms. Context: I will give you one or more API endpoint handlers, route definitions, validation schemas, example responses, and optional business context. The code may be incomplete, spread across files, or mixed with framework boilerplate. Task: Produce accurate, developer-facing API documentation that another engineer can use without reading the original code first. Constraints: - Use only behavior supported by the code or by clearly labeled assumptions. - Do not invent parameters, status codes, auth rules, rate limits, or side effects that are not shown. - If the code is ambiguous, create an "Open questions" section instead of guessing. - Keep naming consistent with the source code. - Prefer concrete examples over abstract explanations. - Call out risky gaps such as missing validation, undocumented error paths, or unclear auth behavior. Output Format: 1. Endpoint Summary - Method: [HTTP METHOD] - Path: [ENDPOINT PATH] - Purpose: one paragraph 2. Authentication and Permissions 3. Request Details - Path parameters - Query parameters - Headers - Request body schema - Validation rules 4. Response Details - Success response with JSON example - Error responses with likely causes 5. Business Logic Notes - Important side effects - Derived fields or hidden rules 6. Edge Cases and Limitations 7. Open Questions 8. Ready-to-publish docs block in clean Markdown Input to use: - Framework/language: [FRAMEWORK OR LANGUAGE] - Route definition(s): [PASTE ROUTE CODE] - Handler/service code: [PASTE HANDLER OR SERVICE CODE] - Validation schema: [PASTE SCHEMA OR "none"] - Example request/response: [PASTE EXAMPLES OR "none"] - Business context: [OPTIONAL CONTEXT OR "none"]
Result
Endpoint Summary - Method: POST - Path: /v1/projects/{projectId}/invites - Purpose: Creates a pending workspace invite for a new team member and optionally sends an email invitation. This endpoint is intended for project admins who need to grant access without manually provisioning users in the dashboard. The code shows that the invite is tied to a specific project, stores the target email in normalized lowercase form, and rejects duplicate active invites for the same address.
Authentication and Permissions The route is protected by `requireSession()` and then checks `assertProjectRole(projectId, user.id, ['owner', 'admin'])`. That means authenticated users can call the endpoint, but only project owners and admins can successfully create invites. There is no evidence of token-based API authentication in the provided code, so this should be documented as session-authenticated unless another auth layer exists outside the snippet.
Request Details **Path parameters** - `projectId` (string, required): Unique project identifier used to scope the invite and permission check.
**Headers** - `Content-Type: application/json` - Auth session cookie or equivalent session header, required by `requireSession()`
**Request body schema** ```json { "email": "[email protected]", "role": "editor", "sendEmail": true } ```
**Validation rules** - `email` must be present, trimmed, lowercased, and pass email validation - `role` must be one of `viewer`, `editor`, or `admin` - `sendEmail` is optional and defaults to `true`
Response Details **Success, 201 Created** ```json { "inviteId": "inv_8f2c1", "projectId": "prj_123", "email": "[email protected]", "role": "editor", "status": "pending", "expiresAt": "2026-05-02T10:30:00.000Z" } ```
**Error responses** - `400 Bad Request`: invalid email, invalid role, or malformed JSON body - `403 Forbidden`: caller is authenticated but lacks admin or owner role - `409 Conflict`: an active invite for the same email already exists in this project
Business Logic Notes - Invite expiration is derived from `now + 7 days`, not supplied by the caller - Duplicate checking happens before insert, but the snippet does not show a unique DB constraint, so concurrent requests may still race unless enforced elsewhere - If `sendEmail` is true, the endpoint queues `mail.enqueueProjectInvite()` after the database write
Edge Cases and Limitations - The code does not show rate limiting, so bulk invite abuse protection is unclear - Error handling around email queue failure is ambiguous. If queuing fails after insert, the invite may exist without an email being sent - There is no visible audit-log write, which may matter for enterprise customers
Open Questions - Is there a database uniqueness constraint on `(projectId, email, status=pending)`? - What happens if `mail.enqueueProjectInvite()` fails after the invite row is created? - Are service tokens allowed to use this endpoint, or only browser sessions?
Ready-to-publish docs block in clean Markdown ### Create a project invite Creates a pending invite for a new project member. Only project owners and admins can call this endpoint. The server validates the email, checks the requested role, prevents duplicate active invites, and returns the new pending invite object.
**POST** `/v1/projects/{projectId}/invites`
**Requires authentication:** Yes **Required role:** `owner` or `admin`
#### Request body - `email` string, required - `role` enum (`viewer`, `editor`, `admin`), required - `sendEmail` boolean, optional, default `true`
#### Success response Returns `201 Created` with the pending invite object, including `inviteId`, `projectId`, `email`, `role`, `status`, and `expiresAt`.
#### Common errors - `400` invalid input - `403` insufficient permissions - `409` duplicate pending invite
وثائق API تتعطل عادة بالطريقة نفسها. يتم شحن endpoint، ثم يتغير الكود مرة أو مرتين، بينما تتأخر الوثائق أو لا تُكتب أصلاً. النتيجة معروفة: يقرأ المهندسون الـ handler مباشرة، وتكرر فرق الشركاء الأسئلة نفسها في Slack، ويصبح فريق الدعم هو المصدر غير الرسمي للحقيقة.
هذا Prompt صُمم لسد هذه الفجوة. فهو يأخذ route definitions وكود handler وvalidation schema وأمثلة payload ثم يحولها إلى وثائق منظمة يمكن لمطور آخر استخدامها فعلاً. القيمة ليست في التلخيص فقط. هذا Prompt يجبر النموذج على الفصل بين السلوك المثبت في الكود وبين الافتراضات، وعلى سرد الأخطاء المحتملة، وعلى إنشاء open questions عندما يكون الكود غامضاً.
البنية هنا مهمة. جزء Role يضع النموذج في موقع technical writer وbackend engineer في الوقت نفسه، وهذا يرفع الدقة. أما Constraints فتقوم بعمل حقيقي: تمنع اختراع قواعد auth أو parameters أو status codes غير موجودة. في كتابة وثائق API، الجملة الواثقة لكنها الخاطئة أسوأ من جملة ناقصة.
كما أن Output Format يجعل هذا Prompt عملياً. بدلاً من شرح عام وغامض، تحصل على تفاصيل endpoint، ووثائق request وresponse، وملاحظات business logic، وحالات edge case، وكتلة Markdown جاهزة للنشر. هذا يسمح للمطور بالانتقال من الكود إلى مسودة وثائق في خطوة واحدة، ثم قضاء وقت المراجعة على النقاط الغامضة فعلاً بدلاً من البدء من صفحة فارغة.
إذا كان فريقك يشحن API داخلية أو partner APIs أو منتجات موجهة للمطورين، فهذا النوع من Prompt يستحق الحفظ. فهو يقلل احتكاك الإطلاق ويجعل الوثائق أكثر موثوقية لأنها تبدأ من الكود الذي يعمل فعلاً.