---
name: nextjs-api-route-documenter
description: "Produces a copy-ready Markdown reference for one Next.js API route: method, URL, parameters, request and response bodies, auth, and error codes, in the shape a README or wiki page expects. Use when one Next.js API endpoint needs a README or wiki reference with its method, URL, parameters, bodies, auth, and error codes. Do not use for generating the route's code or an OpenAPI file for a whole API. Related topics: coding, next.js."
---

# Next.js API Route Documenter

Produces a copy-ready Markdown reference for one Next.js API route: method, URL, parameters, request and response bodies, auth, and error codes, in the shape a README or wiki page expects.

## When to use

Use this skill when one Next.js API endpoint needs a README or wiki reference with its method, URL, parameters, bodies, auth, and error codes. Do not use it for generating the route's code or an OpenAPI file for a whole API.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Write the Overview from the description so a caller knows what the endpoint does and when to use it.
3. State Method and URL and build the Parameters table with name, type, required, and description, or write None.
4. Render the request and response as fenced JSON examples with realistic values and list each field's meaning.
5. Describe the credential and how it is sent under Authentication, or mark the route public.
6. List the status codes the route can return with their meaning and output the sections in the fixed order as plain Markdown.

## Inputs

- **Route path** (free text, e.g. "/api/users")
- **HTTP method** (choose one: GET, POST, PUT, DELETE, PATCH)
- **Description** (longer free text)
- **Query parameters** (longer free text)
- **Request body schema** (longer free text)
- **Response schema** (longer free text)
- **Authentication required** (choose one: Yes, No)

## Output

Plain Markdown (not wrapped in an outer fence) with sections in this order: Overview, Method, URL, Parameters table, Request Body, Response, Authentication, Errors.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Next.js API Route Documenter

Document this Next.js API route for the project README or wiki.

- Route path: {{Route path}}
- HTTP method: {{HTTP method}}
- Description: {{Description}}
- Query parameters: {{Query parameters}}
- Request body schema: {{Request body schema}}
- Response schema: {{Response schema}}
- Authentication required: {{Authentication required}}

Write for the developer who will call this route without reading its code. Open with the Overview: what the endpoint does and when to call it, in the author's words tightened. State Method and URL on their own lines with the path parameters in braces. Present Parameters as a table with columns name, type, required, description, and say "None" when there are none. Show the Request Body and Response as fenced JSON examples with realistic values, then list each field and its meaning under the example. Under Authentication say what credential is needed and how it is sent (header name and scheme), or state that the route is public. Add an Errors list with the status codes the route can return and what each means, inferred from the method and auth setting (400 for an invalid body, 401 when auth is required, 404 for a missing resource, 405 for other methods). Return the Markdown as plain text, not wrapped in an outer code fence, with the sections in this order: Overview, Method, URL, Parameters, Request Body, Response, Authentication, Errors, and no commentary around it.

## Pitfalls

- Filling the JSON examples with placeholder words like string and number, which tells the caller nothing about real values.
- Omitting the 405 and 401 cases, which are the first errors a new caller hits.
- Documenting what the route should do rather than what the description says it does.
