{"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 review API design for gaps and inconsistencies","description":"Share OpenAPI or design notes with a model to find missing workflows and inconsistent patterns, then validate changes with Redocly CLI lint before merge.","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-review-api-design-for-gaps-and-inconsistencies","__idx":0},"children":["Use AI to review API design for gaps and inconsistencies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can ask a model to read OpenAPI or design notes before handlers ship, then gate changes with Redocly CLI lint in the same pull request. The learn article ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-reviews"},"children":["Use AI to accelerate and improve reviews"]}," covers the wider review pattern; here the focus stays on API shape, workflows, and naming drift while lint covers spec compliance and governance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-design-review-belongs-before-implementation","__idx":1},"children":["When design review belongs before implementation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Early review is cheaper than retrofitting routes, error models, and pagination after clients exist. A model can scan many paths at once and compare them against the story you tell about actors, states, and edge cases. It does not replace your product judgment, but it gives you a second reader that is patient with long YAML."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"inputs-that-make-the-review-specific","__idx":2},"children":["Inputs that make the review specific"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste enough domain context that a newcomer could role-play your user. List primary actors, the workflows they care about, and the invariants you already know, for example holds on inventory or partial refunds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add either a full OpenAPI file or a curated excerpt. If the file is huge, scope the excerpt to the surface you are changing and link to the rest in prose. The goal is signal density, not token volume for its own sake."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"domain-context-block-you-can-paste","__idx":3},"children":["Domain context block you can paste"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"Context: We run a small logistics network for cold freight.\nActors: shippers, carriers, warehouse staff.\nWorkflows: booking a lane, changing pickup windows, recording temperature excursions.\n\nReview this OpenAPI excerpt for gaps and inconsistencies:\n[paste paths, schemas, or notes]\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prompt-skeleton-for-gaps-and-inconsistencies","__idx":4},"children":["Prompt skeleton for gaps and inconsistencies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the ask structured so the answer is easy to triage. You can start from this outline and tune nouns to your domain."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are reviewing an API design for [one sentence domain].\n\nPlease list:\n1. Missing CRUD or state transitions implied by the domain but absent from paths.\n2. Incomplete workflows where a user would reach a dead end.\n3. Naming inconsistencies across resources, parameters, and schema fields.\n4. Edge cases we should model explicitly, including error shapes.\n5. Authentication or authorization gaps relative to the described roles.\n\n[paste OpenAPI or notes]\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signals-the-model-often-finds","__idx":5},"children":["Signals the model often finds"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Across teams, the same review surfaces a short set of themes. Missing companion operations appear when create exists without read or cancel. URL style drifts between ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/resource/{id}"]}," and query variants for the same concept. Domain gaps show up when a user can start a workflow but cannot observe status or reverse an action. Security gaps cluster around admin-only routes that lack explicit scopes or consistent error contracts."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat the list as a prioritized backlog, not a verdict. Some suggestions will not fit your roadmap or risk appetite."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"thin-before-and-after-on-paths-and-verbs","__idx":6},"children":["Thin before and after on paths and verbs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /shipments:\n post:\n summary: Create shipment\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /shipments:\n post:\n summary: Create shipment\n get:\n summary: List shipments for the authenticated account\n /shipments/{shipmentId}:\n get:\n summary: Retrieve a single shipment\n patch:\n summary: Update allowed fields on a draft shipment\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The second sketch does not prove correctness, but it shows how a gap review nudges you toward coherent CRUD before you wire handlers."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n A[Domain context plus OpenAPI] --> B[Model review]\n B --> C[Human edits]\n C --> D[redocly lint]\n D --> E[Pull request]\n","diagramHtml":"","diagramHtmlDark":""},"children":["graph LR\n A[Domain context plus OpenAPI] --> B[Model review]\n B --> C[Human edits]\n C --> D[redocly lint]\n D --> E[Pull request]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The loop is intentionally short. You want feedback while the design is still cheap to edit."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"run-lint-after-you-merge-suggestions","__idx":7},"children":["Run lint after you merge suggestions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you accept changes, run the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/lint"},"children":["lint command"]}," against the same file the model saw. Lint applies preprocessors and rules, reports problems in OpenAPI and related formats, and does not run decorators, which keeps this step focused on spec shape."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In continuous integration, you can point the same command at pull requests so every spec edit repeats the same checks your authors run locally. That repetition matters because models sometimes suggest keywords or vendor extensions your ruleset has not whitelisted yet, and lint catches those mismatches early."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have no local config yet, the command defaults to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/recommended"},"children":["recommended ruleset"]},". You can extend coverage with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/built-in-rules"},"children":["built-in rules"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/configurable-rules"},"children":["configurable rules"]}," as your standards mature."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"align-checks-with-governance","__idx":8},"children":["Align checks with governance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Organizations that treat OpenAPI as law usually centralize how rules are authored and shared. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/api-standards"},"children":["API standards and governance"]}," page describes how CLI and hosted flows can reuse the same configuration so developers see the same violations locally and in automation. For first-time setup, the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/guides/configure-rules"},"children":["guide to configuring a ruleset"]}," walks through a practical baseline you can grow over time."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":9},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ship context, not vibes. Short checklists beat long prose in the prompt."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review one theme at a time when the file is large, for example naming first, then errors, then pagination."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log model findings as tickets with spec anchors so humans can accept or reject with traceability."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Combine model passes with deterministic tools so subjective completeness meets objective gates, which mirrors the guidance in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-reviews"},"children":["Use AI to accelerate and improve reviews"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limits-of-this-pairing","__idx":10},"children":["Limits of this pairing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models do not know your private roadmap, real traffic mixes, or regulatory commitments unless you state them. They can hallucinate fields or routes if you ask for rewrites without grounding them in your repository facts. Lint cannot judge whether a workflow is fair to users, only whether the document obeys configured rules."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":11},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a structured prompt plus domain context to surface gaps early, then let Redocly CLI enforce the rules your team already agreed to. Keep humans in the loop for trade-offs, and treat automation as a safety net rather than a substitute for product sense."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":12},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you are ready to wire the deterministic side of the loop, start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," for installation, first commands, and how lint fits alongside bundling and preview workflows described in the broader ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules"},"children":["rulesets"]}," documentation."]}]},"headings":[{"value":"Use AI to review API design for gaps and inconsistencies","id":"use-ai-to-review-api-design-for-gaps-and-inconsistencies","depth":1},{"value":"When design review belongs before implementation","id":"when-design-review-belongs-before-implementation","depth":2},{"value":"Inputs that make the review specific","id":"inputs-that-make-the-review-specific","depth":2},{"value":"Domain context block you can paste","id":"domain-context-block-you-can-paste","depth":3},{"value":"Prompt skeleton for gaps and inconsistencies","id":"prompt-skeleton-for-gaps-and-inconsistencies","depth":2},{"value":"Signals the model often finds","id":"signals-the-model-often-finds","depth":2},{"value":"Thin before and after on paths and verbs","id":"thin-before-and-after-on-paths-and-verbs","depth":2},{"value":"Run lint after you merge suggestions","id":"run-lint-after-you-merge-suggestions","depth":2},{"value":"Align checks with governance","id":"align-checks-with-governance","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"Limits of this pairing","id":"limits-of-this-pairing","depth":2},{"value":"Summary","id":"summary","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to review API design for gaps and inconsistencies","description":"Share OpenAPI or design notes with a model to find missing workflows and inconsistent patterns, then validate changes with Redocly CLI lint before merge."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-review-api-design-gaps-inconsistencies","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}