Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Code Generation

Generating and Publishing Client SDKs

Generate and ship client SDKs from OpenAPI: choose libraries, handle authentication and errors, add retries in a wrapper, version the package and publish from CI.

A client SDK lets other developers call your API with a typed library instead of raw HTTP. Generated SDKs keep every language in step with the spec, but a raw generator output is rarely a polished product. This lesson covers the choices that make the difference: which generator, how authentication and errors surface, how to add behavior without editing generated files, and how to version and publish.

The commands are read-only (the generator cannot run on this site). The wrapper code is runnable Python so that you can see the patterns.

Choose the generator and library

Most generators have a library option that picks the HTTP stack, and different generators exist for the same language:

Language Generators (examples) Notes
TypeScript typescript-fetch, typescript-axios, typescript-angular Pick the stack your users already have
TypeScript types only openapi-typescript (a separate project) Emits types, you bring your own fetch
Python python with library=urllib3 or asyncio Also python-pydantic-v1, python-fastapi for servers
Java java with library=native, okhttp-gson, webclient native uses the JDK client
Go, C#, Kotlin, Swift, Ruby, PHP one or several each Run list and read config-help

A quick rule: pick the generator whose output you would be happy to read in a stack trace, because users will.

Authentication and servers

If the spec has securitySchemes (chapter 4) the SDK gets configuration slots for them: an API key header, a bearer token, OAuth2 flows. The servers list becomes the default base URL, and users override it for staging.

Terminal
npx openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./sdk-ts \
  --additional-properties=npmName=@acme/bookstore-sdk,npmVersion=1.4.0,supportsES6=true

Errors, retries and logging: use a wrapper

Generated clients throw exceptions on non-2xx responses and do nothing clever about retries. Add that in a thin wrapper class you own, so that regeneration cannot erase it. The stand-in below wraps a fake generated client with retry on 503 and exponential waits (the waits are simulated, not slept).

Python Stand-in: a retry wrapper around a generated client

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.

Only retry safe or idempotent requests (GET, PUT, DELETE). Retrying a POST can create duplicates unless the API supports an idempotency key.

Model objects and optional fields

Generated models turn required into constructor arguments and the rest into optional fields. Pay attention to nullable (3.0) or type: [string, "null"] (3.1): old generators may not understand the 3.1 form. If a client crashes on a null that the spec allows, the spec and generator are out of step, not your code.

Python Stand-in: model from a schema, required versus optional

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.

Versioning and publishing

Follow these habits for SDKs:

  • Version the package from the API version, using semantic versioning. A breaking change in the spec is a major bump of the SDK (see versioning and breaking changes).
  • Generate in CI from a tagged spec, run the SDK's own tests, then publish to npm, PyPI, Maven Central or your registry.
  • Document a short README with install, auth and one example. Generators emit a README and per-API docs you can keep.
  • Smoke test the published package against a staging server before announcing a release.
flowchart LR
  A["Spec tagged v1.4.0"] --> B["CI generates SDKs"]
  B --> C["Run SDK tests"]
  C --> D["Publish to registries"]
  D --> E["Announce release notes"]

Every SDK release starts from a tagged spec, never from a developer's machine.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Where should retry logic for a generated SDK live?

    Edits inside generated files vanish on the next run. A wrapper survives regeneration.
  2. 2. Which HTTP methods are normally safe to retry automatically?

    Idempotent methods can be repeated without extra side effects. POST needs an idempotency key.
  3. 3. A breaking change is made to the API spec. How should the SDK version change?

    Breaking changes require a major version under semantic versioning.

Summary

  • Pick the generator and HTTP library that match your users' stack.
  • Security schemes and servers become configuration in the SDK.
  • Put retries, logging and extras in a wrapper you own.
  • Version the SDK from the spec, generate and publish in CI.
  • The Python wrapper and model builder are stand-ins that show the patterns.

Next: Swagger UI and interactive docs