{"id":"6a39ba3a86dfe812bb05736c","title":"Generating A Typed Client","path":"how-to/technical-articles/2026-06-21-python-reference-server/generating-a-typed-client","contentMarkdown":"# 21-Jun-2026 — Generating a Typed Client from the OpenAPI Document\n\n_____\n\nThis is a companion to [A Python Reference Server](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-06-21-python-reference-server). It answers one narrow question: if you decide to build your own implementation of the Salesforce member API, outside the reference servers we provide, how do you turn the published contract into a typed client in your language?\n\n> **You only need this if you are building your own client or server.** If you adopt the reference server we provide, the typed client and server are already built for you and there is nothing to generate here.\n\n## Where the document is\n\nThe contract package [`@ramblers/sf-contract`](https://github.com/nbarrett/ramblers-salesforce-contract) publishes a committed, static OpenAPI document, attached to each [release tag](https://github.com/nbarrett/ramblers-salesforce-contract/tags):\n\n- [`openapi/openapi.yaml`](https://github.com/nbarrett/ramblers-salesforce-contract/blob/main/openapi/openapi.yaml)\n- [`openapi/openapi.json`](https://github.com/nbarrett/ramblers-salesforce-contract/blob/main/openapi/openapi.json)\n\nEither file is enough. Everything below takes one of them as input. You do not need Node, npm or any TypeScript to use them - they are plain text describing the wire format.\n\n## OpenAPI Generator (any language)\n\nThe recommended general-purpose tool is **[OpenAPI Generator](https://openapi-generator.tech)**. It reads the document and emits a typed client for 50+ targets - Python, Java, C#, Go, Rust, PHP, Kotlin, Swift and more. The easiest way to run it, with nothing to install but Docker, is:\n\n```bash\ndocker run --rm -v \"$PWD:/local\" openapitools/openapi-generator-cli generate \\\n -i /local/openapi.yaml \\\n -g python \\\n -o /local/sf-client-python\n```\n\nSwap `-g python` for `-g java`, `-g csharp`, `-g go` and so on to target a different language. The full [list of generators](https://openapi-generator.tech/docs/generators) is on their site.\n\n## openapi-python-client (recommended for Python)\n\nIf your target is Python, **[openapi-python-client](https://github.com/openapi-generators/openapi-python-client)** produces a cleaner, fully type-annotated client (built on [`httpx`](https://www.python-httpx.org) and [`attrs`](https://www.attrs.org)) that reads more naturally than OpenAPI Generator's Python output:\n\n```bash\npipx run openapi-python-client generate --path openapi.yaml\n```\n\nFor a Python project this is the one to reach for. Use OpenAPI Generator when you need a language it does not cover.\n\n## Proving your client agrees on the wire\n\nWhichever tool you use, the generated client is only as correct as the document it was built from - and the document is kept honest by a [CI check](https://github.com/nbarrett/ramblers-salesforce-contract/blob/main/scripts/check-openapi-sync.ts) that fails if it ever stops matching the [builder](https://github.com/nbarrett/ramblers-salesforce-contract/blob/main/scripts/build-openapi.ts) the servers use. The same portable [conformance check](https://github.com/nbarrett/ramblers-salesforce-server/blob/main/python/tests/test_contract_conformance.py) that the reference servers run against themselves can be pointed at your own server, so you can prove your implementation and your generated client agree on the wire before you rely on them.\n","contentHtml":"

21-Jun-2026 — Generating a Typed Client from the OpenAPI Document

\n
\n

This is a companion to A Python Reference Server. It answers one narrow question: if you decide to build your own implementation of the Salesforce member API, outside the reference servers we provide, how do you turn the published contract into a typed client in your language?

\n
\n

You only need this if you are building your own client or server. If you adopt the reference server we provide, the typed client and server are already built for you and there is nothing to generate here.

\n
\n

Where the document is

\n

The contract package @ramblers/sf-contract publishes a committed, static OpenAPI document, attached to each release tag:

\n\n

Either file is enough. Everything below takes one of them as input. You do not need Node, npm or any TypeScript to use them - they are plain text describing the wire format.

\n

OpenAPI Generator (any language)

\n

The recommended general-purpose tool is OpenAPI Generator. It reads the document and emits a typed client for 50+ targets - Python, Java, C#, Go, Rust, PHP, Kotlin, Swift and more. The easiest way to run it, with nothing to install but Docker, is:

\n
docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli generate \\\n  -i /local/openapi.yaml \\\n  -g python \\\n  -o /local/sf-client-python\n
\n

Swap -g python for -g java, -g csharp, -g go and so on to target a different language. The full list of generators is on their site.

\n

openapi-python-client (recommended for Python)

\n

If your target is Python, openapi-python-client produces a cleaner, fully type-annotated client (built on httpx and attrs) that reads more naturally than OpenAPI Generator's Python output:

\n
pipx run openapi-python-client generate --path openapi.yaml\n
\n

For a Python project this is the one to reach for. Use OpenAPI Generator when you need a language it does not cover.

\n

Proving your client agrees on the wire

\n

Whichever tool you use, the generated client is only as correct as the document it was built from - and the document is kept honest by a CI check that fails if it ever stops matching the builder the servers use. The same portable conformance check that the reference servers run against themselves can be pointed at your own server, so you can prove your implementation and your generated client agree on the wire before you rely on them.

\n"}