Gera Tools

API Documentation Prompt Builder

Build prompts for generating clear API endpoint documentation

Enter an endpoint signature, request and response schema, and authentication type to generate a precise AI prompt that produces fully formatted API documentation in OpenAPI 3.1 YAML or clean Markdown. It runs free in your browser on Gera Tools, with nothing uploaded.

Last updated Source: Gera Tools

What output formats are supported?

Two — clean Markdown reference (summary, parameter tables, curl example, response example, errors) or a valid OpenAPI 3.1 path item object in YAML for the single endpoint.

Ship accurate API docs without writing them by hand

Good API documentation is repetitive to write and easy to get subtly wrong. This builder takes the parts only you know — the endpoint, its schemas, and how it is authenticated — and produces a tightly scoped prompt that an LLM turns into complete, correctly formatted reference docs.

How it works

You provide six inputs: method, path, request schema, response schema, authentication scheme, and output format. The tool injects them into a prompt template engineered for accuracy. Key instructions tell the model to describe the endpoint in one sentence, enumerate every parameter with type and required flag, include a realistic curl example and matching response, and document the likely error codes. Critically, the prompt forbids inventing or dropping fields, so the docs match the schema you pasted.

Choosing OpenAPI 3.1 swaps the output instruction to emit a valid YAML path item — parameters, requestBody, responses, and security — ready to paste into a spec file. Markdown produces human-readable reference docs instead.

What each output format is good for

Markdown reference docs are best when the documentation will be read by developers in a portal, README, or docs site. The format includes a human-readable summary, a parameter table with types and required flags, a realistic curl example with a realistic response body, and a table of error codes. This is the format to use when readers need to understand the endpoint quickly.

OpenAPI 3.1 YAML is best when the documentation feeds tooling — SDKs, mock servers, API gateways, or spec-driven testing. The generated path item follows the paths object structure: parameters, requestBody, responses with status codes, and a security entry matching your auth scheme. You paste it under the correct path in your existing openapi.yaml file.

A worked example

For an endpoint like POST /users/{id}/notifications with a body containing type (string, enum: email|sms) and message (string, max 500 chars), authenticated with a Bearer token:

The Markdown output would produce a summary sentence, a two-row parameter table for type and message, a curl example with a plausible JSON body, a matching 200 response example, and a 400 (validation error) and 401 (missing token) error table.

The OpenAPI output would produce a YAML block ready to paste, including requestBody with the schema inline, responses for 200, 400, and 401, and a bearerAuth security entry.

Tips for cleaner results

  • Write schemas as field: type, notes lines — the model uses the notes to fill in descriptions and constraints.
  • Include enum values and defaults in the notes (e.g. status: string (pending|shipped)); the model carries them into the parameter table.
  • For OpenAPI output, run several endpoints and merge the path items under a single paths: key in your spec.
  • If a 4xx case is business-specific, add it to the schema notes so the model documents it correctly rather than guessing.
  • Review the output before committing — the no-invent instruction helps, but always cross-check parameter names and required flags against your actual implementation.