Generate a Spring Boot Server Stub from an OpenAPI 3.0 Spec

Start with the contract, not the controller

Many API projects begin with a controller class and a database model, then someone writes the documentation afterward. The result is usually drift: the Swagger UI shows an endpoint that does not exist, or the code accepts a field the spec forbids.

A more reliable approach is to treat the OpenAPI 3.0 document as the source of truth and generate the server stub from it. OpenAPI Generator reads a YAML or JSON spec and emits endpoint interfaces, request and response model classes, and basic validation scaffolding. Your team then fills in the business logic. The spec stays in sync with the routes because both come from the same file.

What the generator produces

From an OpenAPI 3.0 spec, the CLI generates a full project structure for the target language. For a Spring Boot target, that typically includes a Spring Boot application class, controller interfaces, model POJOs, and a pom.xml or build.gradle with the generator’s chosen dependencies. It does not include your authentication filters, database repository, or business rules. Those are added separately.

Worked example: scaffold a Spring Boot stub

Run this in a terminal on a machine with Docker available. Mount the folder that holds your spec so the container can read it, and point the output at a local directory you control.

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/petstore.yaml \
  -g spring-boot \
  -o /local/out/petstore-server \
  --package-name com.example.petstore

Where to run: your local workstation or a CI runner. Required permissions: read access to petstore.yaml and write access to the output directory. Placeholders: replace petstore.yaml with your spec path, out/petstore-server with your desired output folder, and com.example.petstore with your package name.

Expected checks: after the command finishes, list the output directory. You should see pom.xml or build.gradle, a src/main/java tree, and a src/main/resources folder containing the generated OpenAPI resources. Risks: generation overwrites files inside the output directory, so never commit handwritten code there. A mismatch between the CLI version and the spec’s openapi version can produce invalid imports or missing annotations.

Where to add your own code

The generated controller is usually an interface with method signatures derived from your paths. Implement that interface in a service class you write yourself, then register it as a Spring bean. Add security filters, logging, and transaction handling outside the generated sources. If you edit generated files directly, the next regeneration will discard your changes.

Limitations and version discipline

Pin both the OpenAPI Generator version and the openapi field in your spec. Moving from OpenAPI 2.0 to 3.0 changes how servers, security schemes, and callbacks are described, and the generator behaves differently for each. Enterprise style guides usually require post-processing: generated class names, formatting, and exception handling rarely match an internal standard out of the box.

Generation is a starting point, not a finished server. You still need connection pooling, migration scripts, observability, and deployment configuration.

Verify the generated server matches the spec

Build and start the project from the output directory, for example with ./mvnw spring-boot:run or the Gradle equivalent. Once it is running, open the generated API documentation path—commonly /swagger-ui.html or /swagger-ui/index.html, depending on the Spring Boot version—and confirm the listed endpoints match your spec.

A faster command-line check is to request the OpenAPI document from the running server and compare its path keys to your source file:

curl -s http://localhost:8080/v3/api-docs | jq '.paths | keys'

If the keys match petstore.yaml, the contract survived code generation. If they do not, inspect the generated controller interfaces for missing or renamed operations before writing business logic.

Regenerate when the contract changes

Update petstore.yaml, rerun the generator command, and re-implement any methods whose signatures changed. Treat the generated folder as disposable build output: if something goes wrong, delete it and run the command again. The spec, not the generated Java, is the artifact your team reviews and approves.