این Prompt برای مستندات API، کد endpoint را به داکیومنت قابل انتشار تبدیل میکند
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 میروند، تیمهای partner همان سؤالها را در Slack تکرار میکنند و تیم support به منبع غیررسمی حقیقت تبدیل میشود.
این Prompt برای همین شکاف طراحی شده است. route definition، کد handler، validation schema و نمونه payload را میگیرد و آنها را به مستنداتی ساختاریافته تبدیل میکند که یک توسعهدهنده دیگر واقعاً بتواند استفاده کند. بخش مهم فقط خلاصهسازی نیست. Prompt مدل را مجبور میکند رفتار مستندشده را از فرضیات جدا کند، خطاهای محتمل را فهرست کند و وقتی کد مبهم است، open question بسازد.
ساختار اینجا اهمیت دارد. Role مدل را همزمان در جایگاه technical writer و backend engineer قرار میدهد و همین دقت را بالا میبرد. Constraints هم کار واقعی انجام میدهند: جلوی auth rule ساختگی، parameter حدسی و status code جعلی را میگیرند. در نوشتن API docs، یک جمله اشتباه اما مطمئن از نبودن آن جمله بدتر است.
Output Format هم این Prompt را کاربردی میکند. بهجای یک توضیح مبهم، خروجی شامل جزئیات endpoint، مستندات request و response، نکات business logic، edge caseها و یک بلوک Markdown آماده انتشار است. یعنی توسعهدهنده میتواند در یک مرحله از کد به پیشنویس داکیومنت برسد و زمان بازبینی را صرف بخشهای واقعاً مبهم کند، نه شروع از صفحه خالی.
اگر تیم شما API داخلی، partner API یا محصول developer-facing منتشر میکند، این از آن Promptهایی است که ارزش ذخیره کردن دارد. اصطکاک انتشار را کم میکند و باعث میشود مستندات قابل اعتمادتر شوند، چون از همان کدی شروع میشود که واقعاً در حال اجراست.