{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-learn/ai-for-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Learn","type":"markdown"},"seo":{"title":"Use AI to generate first drafts from your OpenAPI spec","description":"How to prompt an LLM from OpenAPI for summaries and examples, what humans must still verify, and how Redoc renders the page while Redocly CLI decorators and lint keep the spec trustworthy.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-generate-first-drafts-from-your-openapi-spec","__idx":0},"children":["Use AI to generate first drafts from your OpenAPI spec"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The spec already names operations, parameters, and schemas. Readers still need prose that explains tasks, highlights required fields, and shows realistic examples. A large language model can draft that layer quickly, but it will invent details if you let it. Keep the spec authoritative, render with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/redoc"},"children":["Redoc CE documentation"]},", and run ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/api-standards"},"children":["API standards and governance"]}," so text and schema stay aligned before you ship."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This article covers what belongs in a first pass, what humans must verify, and how Redoc plus CLI decorators publish enriched output without silently rewriting the YAML people review in Git."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-belongs-in-a-first-draft-from-openapi","__idx":1},"children":["What belongs in a first draft from OpenAPI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Readers search for a task before they read raw ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]},". A useful first pass adds a short overview per important operation, a parameter table that marks required fields, request and response examples grounded in schemas, and links to related errors or follow-on calls. Cover auth, pagination, idempotency, and limits once, then link from operations that depend on them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Thin specs yield thin drafts. When descriptions are empty, paste release notes or FAQs beside the prompt and label them non-authoritative so nobody treats model text as a spec edit by accident."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-models-handle-well-versus-what-humans-still-own","__idx":2},"children":["What models handle well versus what humans still own"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models compress structure into readable prose fast. They handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oneOf"]}," and discriminator shapes, summarize enums without raw JSON dumps, and draft curl-shaped examples when you name your stack."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Humans still own factual accuracy, legal wording, performance claims, and private routing rules the file never recorded. You own brand tone and which operations belong in public docs. If a field is deprecated in chat but not in OpenAPI, paste that fact next to the prompt or fix the spec first."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-to-prompt-ai-with-your-openapi-file","__idx":3},"children":["How to prompt AI with your OpenAPI file"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"context-block-template","__idx":4},"children":["Context block template"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste something shaped like this before the YAML or JSON:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are drafting human-facing API reference prose from OpenAPI 3.1.\n\nAudience:\n- Backend engineers integrating for the first time this week.\n\nRules:\n- Do not invent endpoints, fields, status codes, or headers that are not in the pasted spec.\n- When the spec is ambiguous, write \"unspecified in OpenAPI\" instead of guessing.\n- Prefer short paragraphs and Markdown tables for parameters.\n\nDeliverables per listed operationId:\n1. A two to four sentence overview of what the call does in product terms.\n2. A Markdown table: name, in, required, type, description (copy descriptions from the spec when present).\n3. One request example and one success response example using realistic but fake data.\n4. Links (relative Markdown) to auth and error reference pages if those paths exist in the same repo outline I paste below.\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste the same OpenAPI slice readers will see, bundled if your repo splits files across folders. If navigation lives outside the spec, paste that outline too so cross-links in the draft match your sidebar."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"review-checklist-for-the-model","__idx":5},"children":["Review checklist for the model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cover error bodies, security per operation, and any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["examples"]}," fields so JSON matches declared types. Require a short assumptions list anywhere the model went beyond the file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-redoc-turns-the-spec-into-a-reference-site","__idx":6},"children":["How Redoc turns the spec into a reference site"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/redoc"},"children":["Redoc CE documentation"]}," describes the three-panel layout readers expect: navigation, operation detail, nested schemas. Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/redoc/quickstart"},"children":["Redoc CE quickstart"]}," or run the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/build-docs"},"children":["build-docs command"]}," through ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," so CI emits static HTML from the same file the model read."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When prose overclaims behavior, comparing the draft to the rendered schema panel surfaces the gap quickly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"where-redocly-cli-decorators-and-lint-fit","__idx":7},"children":["Where Redocly CLI decorators and lint fit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/decorators"},"children":["Decorators"]}," apply repeatable build-time edits: filter internal operations, add examples, or tune descriptions for publication while engineering keeps a stricter root file, as described under ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/api-standards"},"children":["API standards and governance"]},". That split helps when AI suggests friendlier copy you are not ready to merge into canonical YAML."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you change the OpenAPI itself, run ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/built-in-rules"},"children":["built-in rules"]}," through the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/guides/configure-rules"},"children":["guide to configuring a ruleset"]}," so examples still validate and required fields stay consistent."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-ai-cannot-guarantee","__idx":8},"children":["What AI cannot guarantee"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models cannot certify that examples hit your staging stack, that quotas match production, or that legal text is correct per region. Pasting live tokens to chase realism leaks secrets."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use AI to shorten reading time. Use reviewers plus automated lint to certify what readers may rely on."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":9},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Paste bundled OpenAPI or the exact slice you publish so paths and component names match what Redoc will render."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ask the model to output a change list of assumptions separate from spec-backed text."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Put decorator-driven publication tweaks in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," so they are reviewable like code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Run lint on the spec after every merge that touches examples or descriptions."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-approach-cannot-replace","__idx":10},"children":["What this approach cannot replace"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This approach cannot replace ship-team review, legal review of commitments, or research on the tasks readers perform. It speeds structure-to-HTML work; it does not transfer ownership of API behavior."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-the-pieces-fit-together","__idx":11},"children":["How the pieces fit together"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n O[OpenAPI source] --> L[LLM prose draft]\n L --> H[Human edits spec or text]\n H --> C[Redocly CLI lint and decorate]\n C --> B[build-docs output]\n B --> P[Redoc layout for readers]\n","diagramHtml":"","diagramHtmlDark":""},"children":["graph LR\n O[OpenAPI source] --> L[LLM prose draft]\n L --> H[Human edits spec or text]\n H --> C[Redocly CLI lint and decorate]\n C --> B[build-docs output]\n B --> P[Redoc layout for readers]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Structure becomes prose, then CLI tooling ties published pages back to the same rules on every build."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":12},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/redoc"},"children":["Redoc CE documentation"]}," and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/redoc/quickstart"},"children":["Redoc CE quickstart"]}," when you want OpenAPI to become a navigable reference layout."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]},", the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/build-docs"},"children":["build-docs command"]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/decorators"},"children":["decorators"]}," when you want lintable specs, repeatable enrichments, and static HTML in one pipeline."]}]},"headings":[{"value":"Use AI to generate first drafts from your OpenAPI spec","id":"use-ai-to-generate-first-drafts-from-your-openapi-spec","depth":1},{"value":"What belongs in a first draft from OpenAPI","id":"what-belongs-in-a-first-draft-from-openapi","depth":2},{"value":"What models handle well versus what humans still own","id":"what-models-handle-well-versus-what-humans-still-own","depth":2},{"value":"How to prompt AI with your OpenAPI file","id":"how-to-prompt-ai-with-your-openapi-file","depth":2},{"value":"Context block template","id":"context-block-template","depth":3},{"value":"Review checklist for the model","id":"review-checklist-for-the-model","depth":3},{"value":"How Redoc turns the spec into a reference site","id":"how-redoc-turns-the-spec-into-a-reference-site","depth":2},{"value":"Where Redocly CLI decorators and lint fit","id":"where-redocly-cli-decorators-and-lint-fit","depth":2},{"value":"What AI cannot guarantee","id":"what-ai-cannot-guarantee","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What this approach cannot replace","id":"what-this-approach-cannot-replace","depth":2},{"value":"How the pieces fit together","id":"how-the-pieces-fit-together","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to generate first drafts from your OpenAPI spec","description":"How to prompt an LLM from OpenAPI for summaries and examples, what humans must still verify, and how Redoc renders the page while Redocly CLI decorators and lint keep the spec trustworthy."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-generate-first-drafts-from-openapi","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}