Generating client SDKs from the OpenAPI spec

Pulp Engine ships first-class clients for:

Language	Package	Hand-written or generated?
TypeScript	`@pulp-engine/sdk`	Hand-written
Python	`pulp-engine` on PyPI	Hand-written
.NET (C#)	`PulpEngine.Sdk`	Generated from `openapi.json` via openapi-generator
Go	`github.com/TroyCoderBoy/pulp-engine/packages/sdk-go`	Generated from `openapi.json` via openapi-generator
Java, Ruby, PHP, Kotlin, Swift, Rust, …	Not shipped as a first-class package. Operators generate on demand from `openapi.json` — see § Generating a client with openapi-generator.	User-generated

The .NET and Go SDKs are the first two languages served by the generator-driven track. The TypeScript and Python SDKs predate the OpenAPI surface being first-class and remain hand-written; new languages join the generator track instead so the maintenance cost stays bounded.

For languages outside the supported set — Ruby, PHP, Kotlin, Swift, Rust, etc. — you can auto-generate a client yourself from the OpenAPI 3.0.3 specification at openapi.json (repo root). The spec is regenerated from the live Fastify server via pnpm extract-openapi and CI verifies it stays fresh on every PR via two gates: pnpm extract-openapi --check (catches stale spec) and pnpm sdk:generate --check (catches stale generated SDKs).

Where to find the spec

Source	Location
Repo file (always current)	`openapi.json`
Live API (when `DOCS_ENABLED=true`)	`GET /docs/json`
Swagger UI (when `DOCS_ENABLED=true`)	`GET /docs`

Production note: DOCS_ENABLED defaults to false in production Docker images. To download the spec from a running server, either run a development instance or fetch the file from the repo.

Generating a client with openapi-generator

openapi-generator supports 50+ languages. Install it via:

# npm (no JRE required for the CLI wrapper)
npm install -g @openapitools/openapi-generator-cli

# Or via Docker
docker pull openapitools/openapi-generator-cli

C# / .NET — use the official package

Don’t generate this one yourself. Pulp Engine ships an official PulpEngine.Sdk NuGet package built from the same openapi.json via this exact recipe. Install it directly:
dotnet add package PulpEngine.Sdk
See packages/sdk-dotnet/README.md for usage. The recipe below remains documented in case you want to fork the SDK or run with a custom config.

openapi-generator-cli generate \
  -i openapi.json \
  -g csharp \
  -o ./sdk-dotnet \
  --additional-properties=targetFramework=net8.0,packageName=PulpEngine.Sdk,library=httpclient

Java

openapi-generator-cli generate \
  -i openapi.json \
  -g java \
  -o ./sdk-java \
  --additional-properties=library=native,groupId=com.pulp-engine,artifactId=pulp-engine-sdk

Go — use the official package

Don’t generate this one yourself. Pulp Engine ships an official Go SDK built from the same openapi.json via this exact recipe. Install it directly:
go get github.com/TroyCoderBoy/pulp-engine/packages/sdk-go@latest
See packages/sdk-go/README.md for usage. The recipe below remains documented in case you want to fork the SDK or run with a custom module path. Note: the Go generator’s moduleName additionalProperty is ignored — the module path in the generator’s go.mod is always github.com/{gitUserId}/{gitRepoId} (a single-segment org/repo pair, no subdirectory). Pulp Engine’s orchestrator post-processes the generated go.mod to rewrite the path to github.com/TroyCoderBoy/pulp-engine-go so the published SDK lives at its canonical import path; see scripts/generate-sdks.ts (rewriteGoModule step) for the exact substitution. If you need a different subdirectory module path in your fork, mirror that post-processing pass after the generator runs.

openapi-generator-cli generate \
  -i openapi.json \
  -g go \
  -o ./sdk-go \
  --git-user-id=yourorg \
  --git-repo-id=yourrepo \
  --additional-properties=packageName=pulp-engine

Other languages

See the openapi-generator generators list for Ruby, PHP, Kotlin, Swift, Rust, etc.

Authentication

Pulp Engine supports two authentication schemes (both defined in the spec):

Scheme	Header	When to use
`ApiKeyAuth`	`X-Api-Key: dk_admin_...`	Server-to-server integrations
`EditorTokenAuth`	`X-Editor-Token: ...`	Short-lived editor session tokens (8h TTL)

Configure your generated client to send the appropriate header on every request. Most generators expose this via a Configuration or RequestInterceptor API.

Reference implementations

When in doubt about resource shape, error handling, or pagination, look at the two hand-crafted SDKs:

TypeScript: packages/sdk-typescript/src/ — resource classes, error mapping, pagination helper
Python: packages/sdk-python/pulp-engine/ — same surface area, snake_case, Pydantic models

Both follow the same resource layout (templates, render, batch, assets, etc.) so the API contract is unambiguous.

Reporting SDK issues

If a generated client misbehaves, the issue is usually one of:

The OpenAPI spec is incomplete or wrong — file an issue against Pulp Engine with the failing endpoint and the generator output
The generator has a bug — file with openapi-generator
Auth headers aren’t being sent — check your generator’s auth configuration

For language-specific tuning (idiomatic naming, async support, etc.), the polished TypeScript and Python SDKs are good models for what to add on top of the generated baseline.

← Back to docs index