Add: Should I use AI to generate my SDK?

learn/ai-for-docs/should-i-use-ai-generate-sdk.md

@@ -0,0 +1,53 @@
+---
+seo:
+ title: Should I use AI to generate my SDK?
+ description: Why asking an LLM to write your SDK from scratch is riskier than it looks, and how deterministic, OpenAPI-driven generation keeps client libraries accurate.
+---
+
+# Should I use AI to generate my SDK?
+
+Someone on the team suggests pointing an LLM at the API and asking it to write a client library, so the docs team can skip the slow generator setup and ship SDKs in a few languages by Friday. It sounds efficient, and for a rough prototype it might even work. Once real customers start importing that library into production code, the question changes from "can AI write this" to "will this compile the same way next week." This article covers what a model can and cannot be trusted with in SDK generation, and where a repeatable, OpenAPI-driven pipeline still has to do the generating itself.
+
+## What "AI generates my SDK" usually means in practice
+
+In most cases, someone pastes an OpenAPI description into a chat window and asks for a Python or JavaScript client. The model returns working-looking code: a class per resource, methods per operation, maybe even docstrings. For a handful of endpoints, that output can look identical to what a real generator would produce, which is exactly what makes the approach tempting.
+
+The trouble shows up at scale. A "hallucination," in this context, means the model invents a parameter, a status code, or a field name that never appeared in the spec, and it does this with the same confident tone it uses for accurate output. You cannot tell which lines are grounded and which are guesses just by reading them, so every method needs a manual check against the source spec before you ship it.
+
+## Where a model helps and where it invents
+
+A model is genuinely useful for the parts of an SDK that are really writing dressed up as code: a friendly wrapper method name, a docstring that explains when to call an endpoint, a usage example in a README. Those pieces benefit from the model's fluency, and a human who knows the product can catch a wrong word quickly because the stakes are low.
+
+Generating the request-building logic itself is a different job. The method signatures, the required-versus-optional fields, the enum values, and the auth headers all need to match the spec exactly, because a client that compiles but sends the wrong field silently breaks integrations instead of failing loudly. That is precise, repeatable work, which is exactly what "deterministic" tools are built for (tools that return the same output every time for the same input) and what a language model, by design, is not.
+
+## Why deterministic generation from OpenAPI wins for the client itself
+
+Feed a code generator the same OpenAPI file twice and you get the same client twice, byte for byte. Feed a large language model the same prompt twice and you can get two different implementations of the same endpoint, because sampling and context length both introduce variance the model does not expose to you.
+
+Redocly's own [documentation platform](https://redocly.com/docs/redoc) already treats generation this way for a related problem: request code samples. Instead of asking a model to invent a curl or Python snippet per endpoint, the platform can [generate code samples automatically](https://redocly.com/docs/api-reference-docs/guides/generate-code-samples) straight from the OpenAPI description, so the sample always matches the current parameters and auth scheme. When a hand-written sample is genuinely better than the generated one, the [`x-codeSamples` extension](https://redocly.com/docs/realm/content/api-docs/openapi-extensions/x-code-samples) lets a team add it to the spec itself, including snippets that call a real SDK, which keeps even the manual exceptions traceable to one source of truth.
+
+A full client library generator works on the same principle, just with more surface area: types, request builders, and serialization all derive from the spec, not from a model's best guess at what your API probably does.
+
+## A workable split: AI on the edges, OpenAPI at the center
+
+The realistic answer to "should I use AI to generate my SDK" is a split, not a yes or no: use AI around the generation step, and let a deterministic tool own the step itself.
+
+### Keep the spec trustworthy first
+
+Any generator, Redocly's own code samples or a dedicated OpenAPI-to-SDK tool, is only as good as the file it reads. [Redocly CLI](https://redocly.com/docs/cli/) applies [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) that catch missing required fields, inconsistent naming, and other spec problems before they turn into a broken method in someone's generated client. Because every team's compatibility policy differs slightly, [configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) on top of a recommended baseline lets you encode the exact rules your SDKs depend on, so lint fails the build instead of a customer filing a ticket. [Decorators](https://redocly.com/docs/cli/decorators) handle the enrichment work, filtering internal-only operations or tuning descriptions for publication, as a reviewable, versioned step rather than a one-off model edit to the YAML.
+
+### Let AI draft the parts a generator can't
+
+Once the spec is trustworthy, AI is a reasonable first pass for everything a generator does not touch: quickstart guides, migration notes between SDK versions, and explanations of why a particular workflow needs two calls instead of one. A model can also review a generated diff and describe what changed in plain language, which speeds up the release notes without letting it anywhere near the generation logic itself.
+
+Backward compatibility deserves particular care here, because a breaking change in a spec becomes a breaking change in compiled client code, not just a line in a changelog. An LLM comparing two spec versions can narrate what looks different, but that review "is not a contract test," so pair it with the same CLI rules that gate every other change, and keep a human in the loop for anything the model flags as uncertain.
+
+## What this approach cannot replace
+
+None of this replaces a real generator, hand-maintained wrapper code where the domain genuinely needs it, or a human reviewing the first release of any new SDK line by line. AI also cannot guarantee that a generated client behaves the same way against your live API as it does against the spec, which is a runtime question rather than a spec-authoring one. Scheduled checks with [Respect](https://redocly.com/docs/respect/) that compare live API behavior to the OpenAPI description catch that mismatch, since a spec can be perfectly linted and still describe a server that has changed underneath it.
+
+Use AI to speed up the writing and reviewing around your SDK. Use a deterministic generator, backed by a linted spec, to write the SDK.
+
+## How Redocly can help
+
+If your team is weighing AI-generated versus deterministically generated client code, the real prerequisite is the same either way: an OpenAPI description that says exactly what your API does. [Redocly CLI](https://redocly.com/docs/cli/) lints that description with rule-based checks and configurable severity, so the types, required fields, and naming any generator relies on stay consistent release after release. That is the same foundation Redocly uses to auto-generate request code samples straight from the spec, and it is the foundation any SDK generator, AI-assisted or not, needs before you can trust what it produces.

learn/ai-for-docs/sidebars.yaml

@@ -10,6 +10,8 @@
   label: Use AI to review API design for backward compatibility risks
 - page: ai-generate-first-drafts-from-openapi.md
   label: Use AI to generate first drafts from your OpenAPI spec
+- page: should-i-use-ai-generate-sdk.md
+  label: Should I use AI to generate my SDK?
 - page: ai-enforce-tone-style-consistency-across-docs.md
   label: Use AI to enforce tone and style consistency across docs
 - page: ai-review-code-examples-completeness-accuracy.md