Generating client code from spec in Spring Boot - Deep Dive

Overview - Generating client code from spec

What is it?

Generating client code from spec means automatically creating code that talks to a server based on a detailed description of the server's API. This description, called a specification, tells what requests the server accepts and what responses it sends back. The generated client code saves developers from writing all the communication details by hand. It helps connect applications smoothly and correctly.

Why it matters

Without generating client code from a spec, developers must write all the code to call APIs manually, which is slow and error-prone. Mistakes in request formats or response handling can cause bugs and wasted time. Automatic generation ensures the client and server understand each other perfectly, speeding up development and reducing bugs. It also makes updating clients easier when the API changes.

Where it fits

Before learning this, you should understand basic REST APIs and how clients and servers communicate. Knowing how to write or read API specifications like OpenAPI helps. After this, you can learn advanced API testing, API versioning, and how to customize generated clients for complex needs.

Mental Model

Core Idea

Generating client code from a spec means turning a clear API contract into ready-to-use code that talks to the server without manual coding.

Think of it like...

It's like having a recipe that lists all ingredients and steps, and instead of cooking yourself, a machine prepares the dish exactly as described.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│ API Spec File │─────▶│ Code Generator│─────▶│ Client Code   │
└───────────────┘      └───────────────┘      └───────────────┘
       ▲                                         │
       │                                         ▼
  (Written by API team)                  (Used by developers)

Build-Up - 7 Steps

1

Foundation

Understanding API Specifications

Concept: Learn what an API specification is and why it describes server endpoints.

An API specification is a document that explains how to talk to a server. It lists all the URLs (endpoints), what data to send, and what data to expect back. The most common format is OpenAPI, which is a structured file (usually JSON or YAML). This spec acts like a contract between the server and clients.

Result

You can read an API spec and understand what requests you can make and what responses to expect.

Knowing the API spec is the foundation because it defines the exact rules for communication that client code must follow.

2

Foundation

What Client Code Does in API Communication

Concept: Understand the role of client code in sending requests and handling responses.

Client code is the part of your application that sends requests to the server and processes the responses. It builds URLs, adds headers, sends data, waits for replies, and converts responses into usable objects. Writing this code manually means repeating similar tasks for every endpoint.

Result

You see how client code acts as a messenger between your app and the server.

Recognizing the repetitive nature of client code shows why automating its creation saves time and reduces errors.

3

Intermediate

Using OpenAPI to Generate Client Code

🤔Before reading on: do you think the generator creates code for all endpoints automatically or only for some? Commit to your answer.

Concept: Learn how tools read OpenAPI specs to produce client code for all described endpoints.

OpenAPI files describe every endpoint, method, parameters, and response types. Tools like OpenAPI Generator or Swagger Codegen read this file and create client classes and methods for each endpoint. These methods handle building requests and parsing responses automatically.

Result

You get ready-to-use client classes that match the API exactly, without writing request code yourself.

Understanding that the generator covers all endpoints ensures you trust the generated client to fully represent the API.

4

Intermediate

Integrating Generated Client in Spring Boot

🤔Before reading on: do you think generated client code works standalone or needs manual wiring in Spring Boot? Commit to your answer.

Concept: Learn how to add generated client code into a Spring Boot project and use it as a service.

After generating client code, you add it as a dependency or module in your Spring Boot app. You can then inject the client classes as beans and call their methods to communicate with the API. This integration allows your app to use the API easily and cleanly.

Result

Your Spring Boot app can call remote APIs through generated client methods as if they were local services.

Knowing how to integrate generated clients into Spring Boot helps you build maintainable and testable applications.

5

Intermediate

Customizing Generated Client Code

🤔Before reading on: do you think generated client code is fixed or can be customized? Commit to your answer.

Concept: Learn how to adjust or extend generated client code to fit special needs.

Generated code is a starting point. You can customize it by adding interceptors, changing timeouts, or extending classes. Many generators allow templates or configuration options to control code style and features. This flexibility helps adapt clients to your project's requirements.

Result

You can tailor generated clients to handle authentication, logging, or error handling as needed.

Understanding customization options prevents frustration when default generated code doesn't fit perfectly.

6

Advanced

Handling API Changes with Regeneration

🤔Before reading on: do you think regenerating client code overwrites your custom changes or merges them? Commit to your answer.

Concept: Learn best practices for updating client code when the API spec changes.

When the API changes, you regenerate client code from the updated spec. To avoid losing custom changes, keep custom code separate (e.g., in subclasses or separate files). Use version control to track changes. This approach keeps your client code up-to-date without breaking your app.

Result

You can safely update client code as APIs evolve, minimizing bugs and manual fixes.

Knowing how to manage regeneration avoids common pitfalls of overwriting custom logic and keeps your app stable.

7

Expert

Internals of Code Generation Tools

🤔Before reading on: do you think code generators parse specs directly or use intermediate models? Commit to your answer.

Concept: Understand how code generators work internally to transform specs into code.

Code generators parse the API spec into an internal model representing endpoints, parameters, and types. They then use templates to produce code files in the target language. This separation allows supporting many languages and customization. Generators also handle complex features like polymorphism and authentication schemes.

Result

You appreciate the complexity behind simple commands that generate client code.

Understanding generator internals helps you debug generation issues and contribute to or customize generators effectively.

Under the Hood

The process starts by reading the API specification file, which is parsed into a structured format representing all API endpoints, methods, parameters, and data models. The generator then applies language-specific templates to this structure, producing source code files that implement client classes and methods. These methods build HTTP requests, serialize parameters, send requests, and deserialize responses according to the spec. The generated code often includes models matching API data schemas and utility classes for configuration and error handling.

Why designed this way?

This design separates the API description from code, enabling automation and consistency. Using templates allows supporting many languages without rewriting core logic. Parsing the spec into an intermediate model makes the process modular and extensible. Alternatives like manual coding are error-prone and slow. Early tools were limited to one language or required manual updates, but modern generators solve these problems by automating and standardizing client creation.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│ API Spec File │─────▶│ Spec Parser   │─────▶│ Intermediate  │─────▶│ Code Templates│
│ (YAML/JSON)   │      │ (Build Model) │      │ Representation│      │ (Language)   │
└───────────────┘      └───────────────┘      └───────────────┘      └───────────────┘
                                                                 │
                                                                 ▼
                                                        ┌─────────────────┐
                                                        │ Generated Client │
                                                        │ Source Code      │
                                                        └─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does generated client code always perfectly match the API without any manual fixes? Commit yes or no.

Common Belief: Generated client code is always perfect and requires no changes.

Reality: Generated code often needs customization or fixes to handle special cases like authentication or error handling.

Why it matters: Assuming perfection leads to bugs or wasted time debugging issues that require simple manual adjustments.

Quick: Do you think regenerating client code overwrites your custom changes automatically? Commit yes or no.

Common Belief: You can freely edit generated code without worrying about losing changes on regeneration.

Reality: Regenerating client code usually overwrites files, so custom changes must be separated or managed carefully.

Why it matters: Ignoring this causes lost work and broken clients after API updates.

Quick: Is generating client code from spec only useful for large projects? Commit yes or no.

Common Belief: Only big projects benefit from client code generation; small projects should write clients manually.

Reality: Even small projects save time and reduce errors by generating client code, especially when APIs evolve.

Why it matters: Avoiding generation in small projects can cause unnecessary manual work and bugs.

Quick: Do you think code generators parse specs directly into code without intermediate steps? Commit yes or no.

Common Belief: Generators convert specs straight into code without intermediate models.

Reality: Generators parse specs into intermediate models before applying templates, enabling flexibility and multi-language support.

Why it matters: Misunderstanding this limits your ability to customize or debug generation processes.

Expert Zone

1

Generated client code often includes hooks or extension points that experienced developers use to add cross-cutting concerns like logging or retries without modifying generated files.

2

Some generators support partial generation, allowing you to generate only models or only API clients, which helps integrate with existing codebases smoothly.

3

Understanding how generators handle polymorphic schemas and inheritance in API models is key to correctly using complex APIs and avoiding runtime errors.

When NOT to use

Generating client code is not ideal when the API is very unstable or changes too frequently, causing constant regeneration overhead. In such cases, using a generic HTTP client with manual request building or dynamic clients like Spring WebClient may be better. Also, for very simple APIs or one-off scripts, manual coding might be faster.

Production Patterns

In production, teams often generate client code as part of their build or CI pipeline to keep clients in sync with API changes. They separate generated code from custom code using packages or modules. Clients are wrapped in service layers that handle retries, circuit breakers, and authentication. Versioning of generated clients aligns with API versions to avoid compatibility issues.

Connections

API Contract Testing

Builds-on

Knowing how client code is generated from specs helps understand how contract tests verify that both client and server follow the same API rules.

Model-View-Controller (MVC) Pattern

Shares pattern

Generated client code acts like the 'Model' in MVC by representing data and communication logic, separating concerns cleanly.

Manufacturing Automation

Similar process

Just as factories automate producing identical parts from blueprints, code generators automate producing client code from API blueprints, improving speed and consistency.

Common Pitfalls

#1 Editing generated client code directly and losing changes after regeneration.

Wrong approach:

public class ApiClient {
// manually added method
public void customMethod() { ... }
// generated code below
...
}

Correct approach:

public class CustomApiClient extends ApiClient {
public void customMethod() { ... }
}

Root cause:

Not separating custom code from generated code causes overwrites when regenerating.

#2 Ignoring API spec updates and continuing to use outdated generated client code.

Wrong approach:

// Using old client code without regeneration
ApiClient client = new ApiClient();
client.callOldEndpoint();

Correct approach:

// Regenerate client code after spec update
ApiClient client = new ApiClient();
client.callNewEndpoint();

Root cause:

Not syncing client code with API spec leads to runtime errors and mismatches.

#3 Assuming generated client code handles all authentication automatically without configuration.

Wrong approach:

// Using generated client without setting auth
ApiClient client = new ApiClient();
client.callEndpoint();

Correct approach:

// Configure authentication in client
ApiClient client = new ApiClient();
client.setAuthToken("token");
client.callEndpoint();

Root cause:

Misunderstanding that generated code often requires manual setup for auth.

Key Takeaways

Generating client code from an API spec automates creating communication code, saving time and reducing errors.

API specifications like OpenAPI act as contracts that code generators use to produce matching client code.

Integrating generated clients into Spring Boot projects allows clean, maintainable API calls as local service methods.

Customizing and managing generated code carefully prevents overwriting changes and handles API evolution smoothly.

Understanding the internal workings of code generators empowers you to debug, customize, and use them effectively.

Practice

1. What is the main benefit of generating client code from an API specification in Spring Boot projects?

easy

A. It automatically deploys the API to the cloud.

B. It saves time and reduces errors when calling APIs.

C. It replaces the need for a backend server.

D. It creates database schemas from the API.

Solution

1. Step 1: Understand the purpose of client code generation

   Generating client code means creating ready-to-use code to call APIs, which saves manual coding effort.

2. Step 2: Identify the main benefit in Spring Boot context

   This process reduces human errors and speeds up development by automating client creation.

3. Final Answer:

   It saves time and reduces errors when calling APIs. -> Option B

4. Quick Check:

   Client code generation = saves time and reduces errors [OK]

Hint: Remember: generated client code automates API calls [OK]

Common Mistakes:

• Thinking it deploys APIs automatically
• Confusing client code with backend code
• Assuming it creates database schemas

2. Which command correctly generates Spring client code using openapi-generator-cli from a spec file named api.yaml?

easy

A. openapi-generator-cli generate -i api.yaml -g spring -o ./client

B. openapi-generator-cli create -i api.yaml -g springboot -o ./client

C. openapi-generator-cli generate -i api.yaml -g java -o ./client

D. openapi-generator-cli build -i api.yaml -g spring -o ./client

Solution

1. Step 1: Identify the correct command syntax for code generation

   The command uses 'generate' to create code, '-i' for input spec, '-g' for generator type, and '-o' for output folder.

2. Step 2: Match the correct generator for Spring client code

   The generator name for Spring client code is 'spring', not 'springboot' or 'java'.

3. Final Answer:

   openapi-generator-cli generate -i api.yaml -g spring -o ./client -> Option A

4. Quick Check:

   Correct command = generate + -g spring [OK]

Hint: Use 'generate' and '-g spring' for Spring client code [OK]

Common Mistakes:

• Using 'create' or 'build' instead of 'generate'
• Using wrong generator name like 'springboot'
• Using '-g java' which is for Java server, not Spring client

3. Given the command openapi-generator-cli generate -i petstore.yaml -g spring -o ./client, what will be the main output?

medium

A. A Spring Boot server application implementing the API

B. A database migration script

C. A JavaScript client library for the API

D. A Spring client library to call the API endpoints

Solution

1. Step 1: Analyze the generator option '-g spring'

   The 'spring' generator creates Spring client code, not server code or JavaScript libraries.

2. Step 2: Understand the output folder './client'

   The generated code will be placed in './client' as a client library to call API endpoints.

3. Final Answer:

   A Spring client library to call the API endpoints -> Option D

4. Quick Check:

   Generator 'spring' = Spring client library [OK]

Hint: '-g spring' generates client code, not server or JS [OK]

Common Mistakes:

• Confusing client code with server implementation
• Expecting JavaScript code from Spring generator
• Thinking it creates database scripts

4. You ran openapi-generator-cli generate -i api.yaml -g springboot -o ./client but got an error: Unknown generator: springboot. What is the likely cause?

medium

A. You need to install Java separately.

B. The input file 'api.yaml' is missing.

C. You used the wrong generator name 'springboot' instead of 'spring'.

D. The output folder './client' already exists.

Solution

1. Step 1: Check the error message details

   The error says 'Unknown generator: springboot', indicating the generator name is invalid.

2. Step 2: Verify correct generator name for Spring client

   The correct generator is 'spring', not 'springboot'. Using 'springboot' causes this error.

3. Final Answer:

   You used the wrong generator name 'springboot' instead of 'spring'. -> Option C

4. Quick Check:

   Error 'Unknown generator' = wrong generator name [OK]

Hint: Check generator name spelling carefully [OK]

Common Mistakes:

• Typing 'springboot' instead of 'spring'
• Ignoring error details
• Assuming missing input file causes this error

5. You want to generate a Spring client from an OpenAPI spec but only want to include APIs tagged with 'user'. Which approach should you take?

hard

A. Modify the OpenAPI spec to only include 'user' tagged APIs before generation.

B. Manually delete unwanted APIs from the generated code after generation.

C. Use --ignore-file-override to exclude APIs by tag.

D. Use the --global-property apis=user option with openapi-generator-cli.

Solution

1. Step 1: Understand filtering options in openapi-generator-cli

   The CLI does not support filtering APIs by tag directly during generation.

2. Step 2: Consider practical ways to generate only 'user' APIs

   Modifying the OpenAPI spec to include only desired tags is the cleanest and recommended approach.

3. Final Answer:

   Modify the OpenAPI spec to only include 'user' tagged APIs before generation. -> Option A

4. Quick Check:

   Filter APIs by editing spec before generation [OK]

Hint: Filter APIs by editing spec before generating client [OK]

Common Mistakes:

• Expecting CLI to filter APIs by tag automatically
• Deleting code manually after generation (error-prone)
• Using unsupported CLI options for filtering