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

_____

This 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?

> **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.

## Where the document is

The 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):

- [`openapi/openapi.yaml`](https://github.com/nbarrett/ramblers-salesforce-contract/blob/main/openapi/openapi.yaml)
- [`openapi/openapi.json`](https://github.com/nbarrett/ramblers-salesforce-contract/blob/main/openapi/openapi.json)

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.

## OpenAPI Generator (any language)

The 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:

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

Swap `-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.

## openapi-python-client (recommended for Python)

If 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:

```bash
pipx run openapi-python-client generate --path openapi.yaml
```

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

## Proving your client agrees on the wire

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](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.