Generating client code from spec in Spring Boot - Mini Project: Build & Apply

Generating client code from spec

📖 Scenario: You are building a Spring Boot application that needs to communicate with an external REST API. The API provides an OpenAPI specification (a contract describing its endpoints and data). To make your work easier, you want to generate client code automatically from this spec instead of writing HTTP calls manually.

🎯 Goal: Learn how to generate Spring Boot client code from an OpenAPI specification file. You will create the spec file, configure the code generator, generate the client code, and integrate it into your Spring Boot project.

📋 What You'll Learn

Create an OpenAPI spec file named petstore.yaml with a simple endpoint

Add a configuration property to specify the location of the spec file

Use the OpenAPI Generator Maven plugin to generate client code from the spec

Include the generated client code in your Spring Boot project

💡 Why This Matters

🌍 Real World

Generating client code from an API spec saves time and reduces errors when integrating with external services. It ensures your client matches the API contract exactly.

💼 Career

Many companies use OpenAPI specs and code generators to build reliable API clients quickly. Knowing how to set this up is a valuable skill for backend and full-stack developers.

1

Create the OpenAPI spec file

Create a file named petstore.yaml in the src/main/resources folder. Add the following minimal OpenAPI spec content exactly as shown:

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

Spring Boot

# Create petstore.yaml file with the exact OpenAPI spec content
# Your code here

Hint

Make sure the file is named exactly petstore.yaml and placed inside src/main/resources.

2

Add OpenAPI spec location configuration

In your pom.xml file, add a property named openapi.spec.path with the value src/main/resources/petstore.yaml. This will tell the generator where to find the spec file.

Spring Boot

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

 property in pom.xml -->
# Your code here

Hint

Add the property inside the <properties> section of your pom.xml.

3

Configure OpenAPI Generator Maven plugin

In your pom.xml, add the OpenAPI Generator Maven plugin inside the <plugins> section. Configure it to use the property ${openapi.spec.path} as the input spec, generate a Spring client, and output to target/generated-sources/openapi. Use the artifactId openapi-generator-maven-plugin and version 6.6.0.

Spring Boot

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string



    src/main/resources/petstore.yaml



# Your code here

Hint

Place the plugin inside the <build><plugins> section of your pom.xml.

4

Include generated client code in Spring Boot project

In your pom.xml, add the generated sources folder target/generated-sources/openapi/src/main/java as a source directory so that Spring Boot can compile the generated client code. Add this inside the <build> section using <sourceDirectory> or <build><plugins><plugin><configuration><sourceDirectories> as appropriate.

Spring Boot

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string



    src/main/resources/petstore.yaml



  
    
      org.openapitools
      openapi-generator-maven-plugin
      6.6.0
      
        
          
            generate
          
          
            ${openapi.spec.path}
            spring
            spring-boot
            ${project.build.directory}/generated-sources/openapi
            
              true
              true
            
          
        
      
    
  

  
  # Your code here

Hint

Add the generated sources folder inside <sourceDirectories> in the <build> section of your pom.xml.

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