35 Prompts for API Docs & Code Comments
The Cadence booking API powers appointment scheduling across three hospital sites and handles roughly 1.2 million bookings a year, but its last OpenAPI file listed every endpoint in one flat page with zero request examples. These 35 prompts rebuild the docs and the in-code comments endpoint by endpoint, written for the way a hospital-integration partner actually reads a reference. Replace anything in brackets with your own routes and fields. For comment conventions that stay readable over time, see the code comment style guide, and for machine-readable output that feeds a docs pipeline, the JSON output prompt pairs well with these.
Endpoint and Reference Entries
Start with one clean reference entry per route before you scatter examples around.
Turn a route and handler into a full reference entry.
You are an API technical writer. Given this route and handler, write a reference entry for the Cadence booking API with: method and path, one-line summary, longer description, parameters table in markdown, request body, success response, and error responses. Audience: an integrating partner at a hospital. Route and handler: [paste code].Write a scannable one-line summary and a longer description.
For the endpoint POST /appointments in the Cadence API, write a one-line summary under 12 words and a 3-sentence description that covers what it does, when a partner should call it, and one guardrail (no double-booking the same slot). No marketing language.Document every query parameter with type, default, and constraint.
List the query parameters for GET /slots?practitionerId=&from=&to= in a table with columns: name, type, required, default, constraint, example. Flag any parameter where the default would surprise a partner. Follow the values in this handler: [paste code].Document path parameters and their validation rules.
Write reference text for the path parameter {appointmentId} in the Cadence API. State its format (UUID v4), where partners get the value, the exact validation error returned for a malformed id, and one example. Keep it to four lines.Write a resource model page for the appointment object.
Write a resource model page for the Appointment object in the Cadence booking API. For each field give type, nullability, description, and an example value. Note that startTime and endTime are always in the practitioner's site timezone. Schema: [paste schema].Convert an OpenAPI file into a human-readable endpoint table.
Read this OpenAPI 3.1 file and produce a table of every endpoint with columns: method, path, summary, auth scope, and whether it is paginated. Sort by resource, then by method. Do not omit deprecated routes; mark them: [paste openapi file].Write the quickstart for a partner’s first booking.
Write a 200-word quickstart for the Cadence booking API: get a token, fetch available slots for a practitioner, book one appointment, and confirm the response. Include a working curl example for each step and the OAuth2 scope required.Request and Response Examples
Examples are where partners fail fastest. Make them realistic, not “foo/bar”.
Generate a realistic booking request body.
Write a realistic JSON request body for POST /appointments in the Cadence API booking a 30-minute follow-up at St. Alder Hospital. Use real-looking but fake patient and practitioner ids, an ISO-8601 start time, and an Idempotency-Key header. Add a one-line rationale per field as a JSON comment.Generate the full 201 response.
Write the 201 Created response body for a successful Cadence booking. Include appointmentId, status, patientId, practitionerId, siteId, startTime, endTime, createdAt, and a links.self. Then annotate each field with a short note explaining what a partner should store.Write a curl example for each endpoint.
Write a copy-paste curl example for each of these Cadence endpoints including headers (Authorization, Content-Type, Idempotency-Key where needed): [list endpoints]. Keep each example to the minimum needed to succeed.Write the same example in Python.
Rewrite this curl example as a Python 3 requests snippet for the Cadence API, using environment variables for the base URL and token, with error handling that prints the error code and message on failure: [paste curl].Document the 409 double-booking response.
Write the 409 Conflict response for a Cadence booking that collides with an existing appointment. Include a machine-readable error code, a human message naming the conflicting appointmentId, and a short "what to do next" note for partners.Show a paginated list response.
Write a realistic paginated response for GET /appointments with 25 items per page. Include data, a nextCursor, and a totalCount. Add a sentence explaining how a partner should page through all results without skipping records created during the loop.Auth, Errors, and Edge Cases
This is the section that stops support tickets before they start.
Document the OAuth2 scopes needed per endpoint.
For each Cadence endpoint below, state the OAuth2 scope required and what happens if the token lacks it (status code and error code). Group by read vs write. Endpoints: [list endpoints].Write a catalog of error codes with causes and fixes.
Write an error-code catalog for the Cadence booking API as a table: HTTP status, error code, cause, and the fix a partner should apply. Cover validation, auth, conflict, rate limit, and upstream-hospital-timeout errors.Document rate limits and Retry-After behavior.
Write a short section on rate limiting for the Cadence API: the limit (600 requests per minute per client), which headers expose the remaining quota, and exactly how a partner should honor a 429 with Retry-After. Include a retry snippet with exponential backoff.Document the Idempotency-Key requirement on writes.
Explain the Idempotency-Key header for the Cadence API: which methods require it, how long keys are retained (24 hours), what happens on a duplicate key, and how a partner should generate and store keys. Include one concrete example.Document timezone and DST handling for slots.
Write a paragraph explaining how the Cadence API handles slot times across daylight-saving changes. State that all timestamps are ISO-8601 with offset, that slot boundaries follow the site timezone, and give one example of a booking that spans a DST shift.Document PHI redaction rules.
Write a compliance note for the Cadence API explaining which fields are redacted in logs and error responses when they carry patient health information. List the field names that are masked, and note that partners must not log raw request bodies.Inline Code Comments
Comments should explain intent, not restate the line. These prompts target the why.
Add a docstring to a handler function.
Add a docstring to this handler in the Cadence codebase covering: purpose, parameters with types, return value, raised exceptions, and one note about the PHI it touches. Keep it under 12 lines: [paste function].Comment a non-obvious slot-allocation loop.
Explain this slot-allocation loop in a short comment for the next developer. State why it walks backwards from the requested time, what the buffer represents, and the one case that would break it: [paste code].Comment the idempotency check.
Write a two-line comment above this idempotency check in the Cadence booking handler. Say what duplicate it prevents and why the check must run before the write, not after: [paste code].Explain a concurrency lock with a why-comment.
Add a why-comment to this row-level lock in the booking transaction. Explain what race it prevents when two partners book the same slot at once, and why a plain read is not enough: [paste code].Turn a vague TODO into a trackable one.
Rewrite this TODO comment to include an owner, a ticket id, and the condition that makes it safe to remove. Keep it one line: [paste TODO].Write a file-header block comment.
Write a file-header comment for this Cadence module: what it does, who owns it, the data it touches, and any external service it depends on. Match the style at the top of our other files: [paste module].Schema and Type Documentation
Field-level docs are what type-checkers and partners both read.
Document each field of the Appointment schema.
For each field in this Appointment schema, write a description under 20 words that states what it holds and any constraint (format, allowed range, or enum). Do not restate the field name: [paste schema].Document enum values and when each applies.
For the AppointmentStatus enum in the Cadence API, write a table: value, meaning, and the event that moves an appointment into that state. Flags the terminal states: [paste enum].Explain nullable versus optional fields.
For this schema, list which fields are optional (may be absent) versus nullable (may be present as null), and give a partner-facing sentence explaining the practical difference for each: [paste schema].Document a status state machine.
Describe the AppointmentStatus state machine as a transition table: from-state, to-state, and the trigger. Flag any transition a partner cannot cause directly. States: requested, confirmed, checked_in, completed, cancelled, no_show.Write migration notes for a deprecated field.
Write migration notes for renaming the field "doctorId" to "practitionerId" in the Cadence API. State the deprecation date, how long the old field keeps returning, and a before/after example. Tone: direct, no apology padding.Review, Style, and Maintenance
Docs rot fast. These prompts keep them honest as the API changes.
Audit docs against the router for missing endpoints.
Compare this list of documented endpoints against the router definitions and list every route that is implemented but undocumented, and every documented route that no longer exists: docs [paste list], router [paste routes].Enforce a consistent comment style.
Review the comments in this file against our comment style rules and list every violation with a suggested rewrite. Rules: explain why not what, no commented-out code, no restating the line, present tense: [paste file].Find stale examples after a field rename.
Search these docs and examples for uses of the old field name "doctorId" and list every location that needs updating. Include the line number and the corrected text: [paste docs].Write a changelog entry for a breaking change.
Write a changelog entry for the Cadence API version 2.3: a required new header, one renamed field, and one removed endpoint. Format: Added, Changed, Deprecated, Removed. Each item one line, partner-facing.Write the docs review checklist for pull requests.
Write a 10-item checklist a reviewer can run on any Cadence API pull request to confirm the docs and comments are current. Each item must be a yes/no question a reviewer can answer in under a minute.Bonus Habits for Docs That Stay Correct
Document the endpoint you just wrote, not the whole API. A one-endpoint prompt gives the model enough context to be accurate; a “document everything” prompt produces confident filler. Feed it the handler and the schema together. Descriptions drift when the writer cannot see the code that enforces them. Keep a single source of truth. If the OpenAPI file is generated from code, generate examples from the same source so they cannot disagree. Review docs in the same PR as the code change. The prompt in a code review that says “also update the reference for {appointmentId}” is the cheapest insurance you have. When the docs must ship as a whole project, the AI README workflow shows how to assemble a document set end to end.
Sources & Notes
These prompts were tested with ChatGPT (GPT-4o class) and Claude 3.5-class models on REST APIs in the healthcare scheduling domain and are model-agnostic. Accuracy improves when you paste the actual handler, schema, or OpenAPI fragment instead of describing it. Error codes, headers, and limits shown here (600 requests per minute, 24-hour idempotency retention, 409 on double-booking) are illustrative; substitute the values your service actually enforces before publishing. For a companion list covering commit, CI, and release documentation, see the related prompt collections on the site.
