Posted inDevelopment

OpenAPI Generator: Saving Developers from the Drudgery of Manual Client SDKs

Development tutorial - IT technology blog
Development tutorial - IT technology blog

The 2 AM Nightmare and the Cost of Manual Coding

The phone vibrates incessantly. Sentry flashes red: TypeError: Cannot read property 'data' of undefined. The production system crashes just because the Backend changed a field from user_id to userId. The Frontend was still calling the old name because the API documentation wasn’t updated in time, and even worse, the entire API Client was handwritten.

I once participated in refactoring a Fintech project with over 50,000 lines of code. The hard-learned lesson: if the Backend and Client aren’t perfectly aligned, all testing efforts are futile when the schema changes. Manually typing every axios.get line or defining hundreds of TypeScript interfaces isn’t just boring; it’s a trap leading to silly typos with serious consequences.

Three Common Scenarios When Connecting APIs

Most development teams today handle communication between services in one of three ways:

1. Manual Craftsmanship (Manual Implementation)

You open Swagger, look at the endpoint, then copy-paste it into your code. This gives you control over every line but is extremely inefficient as the project grows. Imagine a project with 100 endpoints; if the Backend changes a data type from int to string, you’ll have to hunt through dozens of files to fix it manually.

2. Using Generic/Shared Libraries

Many teams choose to write shared wrappers. However, the biggest hurdle remains “Type-safety.” You still have to redefine Models for each language, leading to inconsistencies where things don’t quite line up.

3. Automation with OpenAPI Generator

This is the choice for modern Microservices systems. With just an openapi.yaml file, this tool automatically generates the entire Client SDK source code for TypeScript, Python, Go, or Java in seconds.

Pros and Cons: Is It as Miraculous as They Say?

Pros:

  • 100% Accurate: The generated SDK always perfectly matches the API Spec.
  • Multi-language: A single spec file works for Mobile (Dart/Swift), Web (TypeScript), and Backend-to-Backend (Go/Python).
  • Blazing Speed: Instead of taking 2 days to write boilerplate, it takes 2 seconds to run a command.

Cons:

  • Verbose Code: Generated files often contain lengthy comments and redundant boilerplate.
  • Complex Configuration: You need time to get used to Mustache templates if you want to customize the code to your team’s style.

Practical Implementation: From Spec to Code in an Instant

Ensure your Backend has exported a standard api-spec.yaml file. If not, request it before you begin.

Step 1: Installation via Docker

Instead of a cumbersome Java or Node.js installation, I always prefer using Docker. This ensures every team member, from Windows to Mac, uses the same generator version.

docker pull openapitools/openapi-generator-cli

Step 2: Generate SDK for TypeScript (Axios)

The Frontend needs strict typing to avoid runtime errors. To create an SDK using Axios, execute the command:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
    -i /local/api-spec.yaml \
    -g typescript-axios \
    -o /local/sdk/typescript

In the sdk/typescript folder, you’ll see an api.ts file full of interfaces. Using it is now effortless:

import { UserApi } from './sdk/typescript';

const userApi = new UserApi();
// Intellisense will accurately suggest parameters and return types
const userInfo = await userApi.getUserById(123);

Step 3: Generate SDK for Python and Go

For Python, the generator creates a setup.py file so you can package it internally. For Go, structs are strictly defined, leveraging the full power of static typing.

# For Python
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
    -i /local/api-spec.yaml -g python -o /local/sdk/python

# For Go
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
    -i /local/api-spec.yaml -g go -o /local/sdk/go

Battle-tested Experience: Don’t Use Default Settings

My biggest mistake when starting out was moving the generated code directly into the main source code. Every time the API updated, all manual customizations in the SDK were completely overwritten.

Keep these 3 rules in mind:

  1. Always use .openapi-generator-ignore: This file works like .gitignore. It protects your custom configuration files from being overwritten by the generator.
  2. Integrate CI/CD: Never run the generator command manually and commit. Set up a GitHub Action to automatically create Pull Requests to update the SDK whenever the spec file changes.
  3. Polish the API Spec: Generated code is only as good as the Spec quality. If the Spec lacks descriptions or has ambiguous type definitions, your SDK will be flooded with useless any types.

Spending an afternoon setting up OpenAPI Generator will save you from dozens of sleepless nights debugging. If your system has 3 or more services, this is no longer an optional “extra”—it’s a requirement for maintaining stability.

Share:
Tags: