Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Code Generation

Generating Server Stubs from an OpenAPI Spec

Learn how server generators turn an OpenAPI document into routes, interfaces and controller stubs, how to keep your own logic separate, and try a stand-in router.

A server stub is the skeleton of an API server produced from a spec. It contains the routes, parameter parsing and model classes, and leaves the business logic empty. You fill in the handlers; the generator guarantees that URLs, parameter names and payload shapes match the contract.

OpenAPI Generator offers server generators for many frameworks (names such as spring, aspnetcore, go-server, python-fastapi, nodejs-express-server, php-laravel). They cannot run on this site, so this lesson is read-only for the real tool and uses a runnable stand-in router written in Python to show the mechanism.

Two styles of server generation

Style How it works Result
Scaffold Generates a full project once; you edit the files Fast start, but regeneration overwrites or conflicts
Interface-based Generates interfaces or abstract classes; you write implementations in separate files Safe to regenerate, the compiler tells you what changed

Prefer the interface style. In Spring, for example, the generator option interfaceOnly=true produces a BooksApi interface with annotated methods, and you write BooksApiController implements BooksApi in your own source folder. When the spec adds an operation, your code stops compiling until you implement it, which is exactly the feedback you want.

Terminal
npx openapi-generator-cli generate \
  -i openapi.yaml -g spring -o ./server \
  --additional-properties=interfaceOnly=true,useSpringBoot3=true,useTags=true

Options differ by generator; use config-help -g <name> to see the ones available.

What a generated route table looks like

Whatever the language, the generator walks each path item and writes one route per operation. The URL template /books/{bookId} becomes the framework's own syntax: /books/:bookId in Express, /books/{bookId} in Spring and FastAPI. The stand-in below does that conversion and wires handlers by operationId, answering 501 Not Implemented for operations that have no handler yet. That is also what a freshly generated stub does.

Python Stand-in: a router built from the 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.

Notice that two routes answer 501 until you write their handlers, and an unknown URL gets 404. The real generators produce the same behavior in their framework's idiom.

Models and validation

Server generators also produce model classes from components/schemas. Many frameworks wire these to validation annotations: required fields, minLength, maximum, pattern, enums. That gives you automatic 400 Bad Request responses for bad input. Check what your generator actually validates; support differs, and some leave all validation to you.

Python Stand-in: validating a request body against a schema

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.

Keeping generated and handwritten code apart

flowchart TB
  S["openapi.yaml"] --> G["Generator"]
  G --> I["Generated interfaces and models<br/>(overwritten every run)"]
  H["Your controllers and services<br/>(never overwritten)"] --> I
  I --> R["Running server"]
  H --> R

The spec produces interfaces; your code implements them from a separate folder.

Rules that keep the project healthy:

  • Generate into a folder that is clearly marked (generated/ or build/generated), and either commit it or build it in CI, never both.
  • Put business logic in classes that implement or call the generated types.
  • Use the ignore file for any scaffold file you do customize.
  • Treat the spec as the source of truth: to add a field, change the spec and regenerate.

A generated server does not prove your behavior matches the spec. It only matches shapes. Contract testing closes that gap.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which server generation style survives regeneration best?

    Interfaces are overwritten safely while your implementations stay untouched, and the compiler flags what changed.
  2. 2. What does a freshly generated, unimplemented stub typically return?

    Handlers are empty, so frameworks answer with a not implemented style response until you write the logic.
  3. 3. How do you add a new field to a response model in a spec-driven server?

    The spec is the source of truth. Edit it, then regenerate so every consumer stays consistent.

Summary

  • Server generators create routes, interfaces and models from the spec and leave handlers to you.
  • Prefer interface-only generation so regeneration is safe.
  • Generated validation depends on the generator; check what it covers.
  • Keep generated and handwritten code in separate folders.
  • The Python router and validator are runnable stand-ins for the idea.

Next: Generating client SDKs