OpenAPI Spec to Markdown API Reference Prompt Template

This prompt is designed for technical writers and documentation engineers who need to convert a complete OpenAPI specification (3.0 or 3.1) into a static, human-readable Markdown API reference. The primary job-to-be-done is generating a single, comprehensive document that includes endpoint tables, parameter details, request/response examples, and error code references—all directly derived from the spec. It is ideal when you have a validated, linted OpenAPI file and need a publishable reference without manually transcribing every field.

Use this prompt when your OpenAPI spec is the source of truth and you want a consistent, structured Markdown output that mirrors the spec's operations, schemas, and security definitions. The prompt expects a complete spec as input; it is not designed for drafting new endpoints, fixing invalid specs, or generating conceptual guides. Before using this prompt, ensure your spec passes structural validation (e.g., against OpenAPI 3.0/3.1 rules) and that all $ref pointers resolve correctly. The harness must verify that every operation, parameter, and schema defined in the spec appears in the generated Markdown, and that no hallucinated endpoints or fields are introduced.

Do not use this prompt for partial specs, code-first API scaffolding, or interactive documentation portals. It produces a static reference, not a dynamic playground. If your spec contains polymorphic schemas (oneOf/anyOf), deprecated endpoints, or complex pagination patterns, you must include explicit instructions in the [CONSTRAINTS] placeholder to handle these cases. For high-risk or regulated APIs, always pair the generated Markdown with a human review step to confirm accuracy, completeness, and security disclosure requirements before publication.

The prompt below is designed to be dropped into your AI harness, CI/CD pipeline, or documentation generation tool. It accepts a raw OpenAPI specification (JSON or YAML) and produces a single, well-organized Markdown file suitable for static site generators, developer portals, or internal wikis. The template uses square-bracket placeholders for all variable inputs—swap these out programmatically before each run. Do not modify the core instruction structure unless you are also updating the corresponding validation harness and evaluation suite.

markdownCopy
You are an API documentation generator. Your task is to convert the provided OpenAPI specification into a complete, human-readable Markdown API reference.

## INPUT
[OPENAPI_SPEC]

## CONSTRAINTS
- Render every path, HTTP method, operation ID, summary, and description exactly as defined in the spec.
- For each operation, produce a table of parameters (name, type, required, location, description).
- For each operation, document all request bodies with their content types and schema summaries.
- For each operation, document all response status codes with their content types, schema summaries, and example references.
- Render all component schemas referenced by operations in a dedicated "Schemas" section at the end of the document.
- Include a top-level "Authentication" section derived from the security schemes object.
- Include a "Base URL" section showing the servers array.
- Use proper Markdown headings (## for sections, ### for operations, #### for sub-details).
- Wrap all example payloads in fenced code blocks with the appropriate content-type language tag (e.g., ```json).
- If an operation is deprecated, add a bold **Deprecated** warning at the top of its section and include the deprecation policy details if present.
- Do not invent endpoints, parameters, or schemas not present in the spec.
- If the spec contains a `description` field that uses Markdown, preserve it verbatim.

## OUTPUT FORMAT
Return a single Markdown document with the following sections in order:
1. # [API Title]
2. ## Base URL
3. ## Authentication
4. ## Endpoints (grouped by tag, with each tag as a ### heading)
5. ## Schemas

## ADDITIONAL RULES
- If [INCLUDE_EXAMPLES] is true, inline the first example from each response and request body schema.
- If [INCLUDE_ERROR_CODES] is true, add an "Error Codes" subsection under each endpoint listing the documented error responses.
- If [TARGET_AUDIENCE] is provided, adjust the tone and explanatory depth accordingly (e.g., "external developers" vs "internal platform team").
- If [STYLE_GUIDE] is provided, apply those formatting rules (e.g., "Google Developer Documentation Style Guide").

To adapt this template, replace the square-bracket placeholders with actual values before each invocation. [OPENAPI_SPEC] should contain the full spec as a string. [INCLUDE_EXAMPLES], [INCLUDE_ERROR_CODES] are boolean flags you can set based on your documentation requirements. [TARGET_AUDIENCE] and [STYLE_GUIDE] are optional strings that can be omitted or set to null if not needed. The prompt is model-agnostic but has been tested with GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro. For very large specs (over 50 endpoints), consider splitting the input by tag and running the prompt per tag group, then concatenating the results to stay within context windows.

Before shipping this prompt to production, wire it into a harness that validates the output. At minimum, check that every operation ID from the source spec appears in the generated Markdown, that no hallucinated endpoints exist, and that all referenced schemas are rendered. For high-stakes public documentation, add a human review step before publication. The next section covers the full implementation harness, including retry logic for malformed output and evaluation criteria you can run in CI.

Integrating this prompt into an application requires treating the generated Markdown as a build artifact, not a one-off copy-paste. The harness should accept an OpenAPI spec (JSON or YAML), validate it structurally before invoking the model, and then feed the spec into the prompt as the [OPENAPI_SPEC] input. Because large specs can exceed context windows, the harness must first segment the spec by path or tag group, process each segment independently, and then concatenate the results into a single Markdown file. This segmentation logic is the most critical part of the implementation—it must preserve cross-references between schemas and endpoints while staying within token limits.

After the model generates Markdown for each segment, the harness must run a validation pass that checks for completeness: every operation, parameter, request body, response schema, and error code defined in the source spec must appear in the output. A practical approach is to parse the original OpenAPI spec and extract a set of expected identifiers (operation IDs, schema names, status codes), then scan the generated Markdown for those identifiers. Any missing entries should trigger a targeted retry with a narrower prompt that includes only the missing sections and a [CONSTRAINTS] block requiring their inclusion. For high-stakes API documentation, add a human review step that samples endpoints and verifies parameter accuracy against the live API before publication.

Model choice matters here. Use a model with strong structured reasoning and long-context handling, such as Claude 3.5 Sonnet or GPT-4o, because the task demands precise schema interpretation and consistent formatting across thousands of lines. Set the temperature low (0.1–0.2) to reduce creative drift in descriptions. For very large specs, consider a two-pass architecture: first, a summarization pass that extracts endpoint summaries and schema descriptions into a compact intermediate format; second, a rendering pass that expands the intermediate format into final Markdown. This reduces token pressure and improves consistency. Always log the prompt version, model version, and spec hash alongside each generation run so you can trace any output anomalies back to their source.