OpenAPI Spec-Driven Developer Portal Content Prompt Template

This prompt is designed for DevRel teams and technical writers who need to produce developer portal content that stays synchronized with a live API contract. Instead of writing tutorials that reference fictional endpoints or stale parameter names, the prompt takes a complete OpenAPI specification as ground truth and generates narrative documentation that references only real operations, schemas, and error codes. The core job-to-be-done is bridging the gap between a machine-readable API contract and the human-readable guides that developers rely on during onboarding and integration.

Use this prompt when you need a getting-started guide, an authentication walkthrough, or a use-case tutorial that must pass automated validation against the spec. The prompt works best when you provide a complete, validated OpenAPI 3.0 or 3.1 document along with a clear content objective—such as 'write a Python quickstart for the Orders API' or 'explain how to authenticate and make your first request.' The harness should be configured to parse the spec, extract relevant operations and schemas, and feed them as structured context alongside your content instructions. Every endpoint, parameter, and error code referenced in the output must be traceable back to the source spec, and the validation layer should flag any hallucinated paths or properties before the content reaches a reviewer.

Do not use this prompt for generating the OpenAPI spec itself, for linting spec structure, or for producing API reference pages. Those tasks belong to sibling playbooks in the OpenAPI and API Specification Authoring group, such as the OpenAPI Specification Scaffold from Code Annotations or the OpenAPI Spec to Markdown API Reference templates. This prompt is also not suitable for content that requires subjective design decisions—like choosing between multiple valid API patterns—without a human reviewer in the loop. If your spec is incomplete, contains unresolved $ref targets, or lacks example payloads, fix those issues first using the validation and example-generation playbooks before feeding the spec into this content-generation workflow.

This prompt template generates getting-started guides, authentication walkthroughs, and use-case narratives directly from an OpenAPI specification. It is designed to be inserted into your prompt assembly pipeline, where upstream processes inject the spec, content type, and audience parameters before the model call. Every generated section must reference real endpoints, schemas, and error codes from the provided spec—the harness should reject outputs that invent operations or parameters not present in the source.

textCopy
You are a developer documentation writer generating portal content from an OpenAPI specification.

[SPEC]
The complete OpenAPI specification in JSON or YAML format. All generated content must reference only endpoints, schemas, parameters, and error codes present in this spec.

[CONTENT_TYPE]
One of: getting-started, authentication-walkthrough, use-case-narrative, endpoint-deep-dive, error-handling-guide, or sdk-integration-pattern.

[AUDIENCE]
Target developer persona and experience level, such as "backend engineers familiar with REST APIs" or "frontend developers new to this service."

[USE_CASE]
For use-case-narrative content type only: the specific workflow to document, such as "creating and managing recurring billing subscriptions" or "bulk importing customer records with async validation."

[OUTPUT_SCHEMA]
{
  "title": "string (page title)",
  "introduction": "string (2-3 sentence overview with prerequisite context)",
  "prerequisites": ["string (concrete prerequisite: auth method, SDK version, account tier)"],
  "sections": [
    {
      "heading": "string",
      "content": "string (markdown with inline code references to spec operations)",
      "code_examples": [
        {
          "language": "string",
          "code": "string",
          "description": "string (what this example demonstrates)"
        }
      ],
      "referenced_operations": ["string (operationId from spec)"]
    }
  ],
  "error_reference": [
    {
      "status_code": "integer",
      "error_code": "string",
      "common_cause": "string",
      "resolution": "string"
    }
  ],
  "next_steps": ["string (link or action for further learning)"]
}

[CONSTRAINTS]
- Every referenced_operations entry must match an operationId in [SPEC].
- Every code_example must use endpoints, parameters, and schemas from [SPEC].
- Every error_reference entry must correspond to a documented response in [SPEC].
- Do not invent endpoints, parameters, or error codes.
- Use the exact field names, enum values, and status codes from [SPEC].
- For authentication-walkthrough: include token acquisition, refresh, and scope requirements.
- For getting-started: minimize time-to-first-success with copy-pasteable commands.
- Mark any spec gaps with "[SPEC GAP: description]" rather than fabricating details.

[EXAMPLES]
Input: getting-started content for a payments API spec with API key auth.
Output includes: API key generation steps, first charge endpoint call with curl example, common 401/402 error resolutions, and link to full endpoint reference.

Input: use-case-narrative for "batch invoice generation" from an invoicing API spec.
Output includes: prerequisite customer and product setup, batch creation endpoint walkthrough, polling for async job status, handling partial failures, and webhook event subscription for completion notifications.

[RISK_LEVEL]
Medium. Generated content will be published to a developer portal. Incorrect endpoint references, missing auth steps, or fabricated error codes will break developer trust and increase support load. Require human review before publication.

Adapt this template by replacing each square-bracket placeholder with real values before sending to the model. The [SPEC] placeholder should receive the full OpenAPI document—do not truncate or summarize it, as the model needs complete schema context to generate accurate references. The [OUTPUT_SCHEMA] enforces structured JSON output; pair this with your model's structured output or JSON mode feature to guarantee parseable results. Before publishing generated content, run a post-generation validation step that extracts every referenced_operations value and confirms it exists in the source spec. Flag any [SPEC GAP] markers for manual documentation work. For high-traffic portal pages, consider caching generated content and re-running generation only when the spec changes.

The harness for this prompt is responsible for ensuring that every piece of generated developer portal content references real endpoints, schemas, and error codes that actually exist in the source OpenAPI specification. Before the prompt ever runs, the harness must parse the spec, extract a machine-readable index of all operation IDs, path patterns, parameter names, schema references, and documented HTTP status codes. This index becomes the ground truth that post-generation validation checks against. Without this harness, the prompt will confidently generate tutorials that reference non-existent endpoints or hallucinated error codes, which erodes developer trust faster than missing documentation.

Pre-validation begins with spec integrity checks. The harness must confirm the OpenAPI spec parses successfully, that all $ref pointers resolve, and that every operation has a unique operationId. If the spec fails these checks, the harness should abort and return a structured error rather than feeding a broken spec to the prompt. Once the spec passes, the harness extracts a lookup table mapping each operationId to its HTTP method, path, available parameters, request body schema reference, and documented response status codes. This table is passed into the prompt as part of the [CONTEXT] placeholder alongside the full spec text. The harness should also inject a [CONSTRAINTS] block that explicitly instructs the model to only reference operations, parameters, and error codes present in the provided spec index, and to mark any referenced endpoint with its exact operationId.

Post-generation validation is where the harness earns its keep. The generated content must be scanned for any API reference—endpoint paths, HTTP methods, parameter names, schema property names, or status codes—and each reference must be checked against the pre-extracted spec index. Any reference that cannot be matched to a real spec element must be flagged. The harness should produce a validation report with three categories: matched references (confirmed in spec), unmatched references (likely hallucinations), and missing coverage (spec operations that exist but were never mentioned in the generated content). A content piece that contains unmatched references should trigger a retry with the validation errors injected into the prompt as additional [CONSTRAINTS], instructing the model to correct or remove the hallucinated references.

Retry logic must be bounded. The harness should attempt a maximum of three regeneration cycles per content piece. On each retry, the validation errors from the previous attempt are appended to the prompt as explicit correction instructions. If after three attempts the content still contains unmatched references, the harness should surface the content with a review-required flag and a detailed error manifest for human triage. This prevents infinite retry loops while ensuring that no hallucinated API surface reaches the developer portal without review. The harness should also log every validation failure with the specific unmatched string, the prompt version, the model used, and the retry count for observability.

Model choice matters for this workflow. The prompt requires strong instruction-following and the ability to cross-reference structured spec data with narrative prose. Models with larger context windows are preferred because full OpenAPI specs can exceed 10,000 tokens before any generated content. If the spec is too large for a single context window, the harness should implement a chunking strategy: split the spec by tag groups or path prefixes, generate portal content per section, and then run a cross-section consistency check to ensure the same endpoint is not documented with conflicting instructions across sections. For high-stakes public documentation, always route the final validated output through a human review queue before publication, regardless of automated validation scores.

Wire this harness into your CI/CD pipeline so that every spec change triggers a re-generation and re-validation of affected portal content. Store the spec version hash alongside each generated content piece to enable diff-based updates rather than full regeneration. When the spec changes, the harness should identify which operations were added, modified, or removed, and only regenerate the tutorial sections that reference those operations. This keeps your developer portal in sync with your API contract without burning compute on unchanged content.