Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Code Generation

How Code Generation from OpenAPI Works

See how tools turn an OpenAPI document into client SDKs, server stubs and models, what they can and cannot generate, and build a tiny generator yourself.

An OpenAPI document describes every path, parameter, request body and response of an API in a machine-readable way. That makes it an ideal input for code generation: a program reads the document and writes source code for you. Instead of hand-writing a client that calls GET /books/{bookId} and parses the JSON, a generator produces a typed method get_book(book_id) in your favorite language.

This chapter covers generation from the practical side: what is generated, how the tools work, and where generation helps or hurts. The real tools (OpenAPI Generator, Swagger Codegen, openapi-typescript and others) are command-line programs that cannot run inside this website. In this lesson you will use a small stand-in generator written in Python that follows the same steps, so you can see the mechanism with your own eyes. Everything labelled "stand-in" is a teaching tool, not the real product.

What can be generated

Generators produce several kinds of output from the same document:

Output What you get Typical use
Client SDK One method per operation, plus request and response models Calling the API from an app or another service
Server stub Routes, controllers or interfaces with empty bodies Implementing a design-first API
Models only Classes or types for every schema in components/schemas Sharing data types
Documentation HTML or Markdown pages Static docs (see Documentation tools)
Config and tests API test skeletons, Postman collections Quick smoke tests

The generator does not know your business rules. It knows shapes: names, types, required fields, status codes. Anything the spec does not say, the generator cannot invent.

The pipeline in four steps

Every generator, from a 200-line script to a large tool with hundreds of language templates, follows the same pipeline:

flowchart LR
  A["OpenAPI document"] --> B["Parse and resolve $ref"]
  B --> C["Build an internal model<br/>operations, models, params"]
  C --> D["Apply templates<br/>one per language"]
  D --> E["Source files"]

The generator reads the spec, builds a neutral model, then renders templates into source code.

  1. Parse and resolve. Load YAML or JSON and follow every $ref so that the tool sees complete schemas.
  2. Build a neutral model. Turn paths into a list of operations (name, method, URL template, parameters, body, responses) and schemas into models.
  3. Apply templates. A template for each language turns the model into text. Changing the template changes the style of every generated file.
  4. Write files. The result is placed in an output folder, often with a manifest of the generated files.

The key detail is naming. The operation name comes from operationId. If you do not set one, generators invent a name from the method and path (getBooksBookId), which tends to be ugly. This is why good operationId values matter so much.

Build a tiny generator

The stand-in below does steps 2 and 3 for a very small Bookstore spec. It creates a Python class source as a string, prints it, then runs it against a fake transport so you can see the generated methods work.

Python Stand-in: generate a Python client from a spec

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The generated source is ordinary code. Real generators add types, error handling, serialization, authentication hooks and docstrings, but the heart is exactly this loop over operations.

Naming rules decide how the SDK feels

Because the generator derives names from the document, small spec changes ripple through the generated code. Compare these two operations:

YAML
# Good: stable, descriptive, verb-first
operationId: listBooks

# Weak: generators invent something unpredictable
# (no operationId at all)

Most generators then convert listBooks to the conventions of each language: listBooks in Java and TypeScript, list_books in Python and Ruby, ListBooks in Go and C#. The next TryIt shows the idea with a small converter, including the awkward case of acronyms and fallbacks for a missing operationId.

Python Stand-in: naming conventions and fallbacks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The fallback shows why you should always set operationId: getBooksBookId is what a generator would produce, and nobody wants to call that.

Strengths and limits

Generation shines when:

  • many languages must call the same API and stay in sync,
  • the spec is the single source of truth (see design-first workflows),
  • you want compile-time errors when the API changes.

It struggles when:

  • the spec is vague (type: object with no properties produces a map of anything),
  • you rely on advanced schema features such as oneOf with discriminators, if/then, or unevaluatedProperties, which many generators only partly support,
  • you hand-edit generated files, because the next run overwrites them.

Keep generated code in its own folder or package, never edit it by hand, and re-generate in CI so the SDK always matches the spec. Put customizations into templates or wrapper classes instead.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Where does a generator usually get the name of a client method?

    The operationId is the intended method name. Without it, tools invent names from the method and path.
  2. 2. What is the first step of the generation pipeline?

    The tool must load the document and resolve references to see complete schemas before it can build a model.
  3. 3. Why should you avoid editing generated files by hand?

    Regeneration replaces the files. Put customizations in templates or wrappers instead.

Summary

  • Generators read an OpenAPI document and write clients, server stubs, models or docs.
  • The pipeline is parse and resolve, build a neutral model, apply templates, write files.
  • operationId drives method names; always set it.
  • Generated code should live apart from hand-written code and be regenerated in CI.
  • The Python generator in this lesson is a stand-in that teaches the mechanism, not the real tool.

Next: OpenAPI Generator on the command line