Client guides on pgmi

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Client Generation#

The advanced template serves an OpenAPI 3.1 specification at GET /openapi.json and an interactive explorer at GET /docs. Use these to generate typed clients in any language.

pgmi does not ship client libraries. Your deployment owns the spec; your pipeline owns the client.

Quick Start#

Deploy your project with pgmi
Open http://localhost:3000/docs for the interactive API explorer
Pick a language below and generate a typed client

Language Recipes#

Language	Tool	Recipe
TypeScript	openapi-typescript	TypeScript
Go	oapi-codegen	Go
Python	openapi-python-client	Python
C#	NSwag	C#
Any	openapi-generator	Generic

HTTP Collections#

For ad-hoc exploration without codegen, see HTTP collections to generate importable request files for Bruno, VS Code REST Client, or IntelliJ.

TypeScript

Mon, 01 Jan 0001 00:00:00 +0000

TypeScript Client Generation#

Generate TypeScript types and a fetch-based client from your deployment’s /openapi.json.

openapi-typescript (types only)#

Generates TypeScript types from the spec. Pair with openapi-fetch for a typed fetch wrapper.

npx openapi-typescript http://localhost:3000/openapi.json -o src/api.d.ts

Use the types with openapi-fetch:

import createClient from "openapi-fetch";
import type { paths } from "./api";

const client = createClient<paths>({ baseUrl: "http://localhost:3000" });

const { data, error } = await client.GET("/hello", {
 params: { query: { name: "World" } },
});

openapi-generator (full client)#

Generates a complete client with models and API classes:

npx @openapitools/openapi-generator-cli generate \
 -i http://localhost:3000/openapi.json \
 -g typescript-fetch \
 -o src/generated

CI Integration#

Add to your build pipeline so the client stays in sync with the spec:

Go

Mon, 01 Jan 0001 00:00:00 +0000

Go Client Generation#

Generate Go types and client code from your deployment’s /openapi.json.

oapi-codegen#

The standard Go OpenAPI code generator. Produces types, client, and server stubs.

go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

# Generate types + client
oapi-codegen -generate types,client \
 -package api \
 -o api/client.gen.go \
 http://localhost:3000/openapi.json

Usage:

package main

import (
 "context"
 "fmt"
 "yourproject/api"
)

func main() {
 client, _ := api.NewClientWithResponses("http://localhost:3000")
 resp, _ := client.HelloWorldWithResponse(context.Background(), &api.HelloWorldParams{
 Name: ptr("World"),
 })
 fmt.Println(resp.JSON200.Message)
}

func ptr[T any](v T) *T { return &v }

go generate#

Add a generate.go file so go generate ./... keeps the client current:

Python

Mon, 01 Jan 0001 00:00:00 +0000

Python Client Generation#

Generate a typed Python client from your deployment’s /openapi.json.

openapi-python-client#

Generates a complete Python package with Pydantic models and an httpx-based client.

pip install openapi-python-client

# Generate client package
openapi-python-client generate \
 --url http://localhost:3000/openapi.json \
 --output-path ./api-client

Usage:

from api_client import Client
from api_client.api.default import hello_world

client = Client(base_url="http://localhost:3000")
response = hello_world.sync(client=client, name="World")
print(response.message)

# Async
response = await hello_world.asyncio(client=client, name="World")

Updating#

When handlers change, regenerate:

openapi-python-client update \
 --url http://localhost:3000/openapi.json \
 --output-path ./api-client

Alternative: openapi-generator#

openapi-generator generate \
 -i http://localhost:3000/openapi.json \
 -g python \
 -o ./api-client

C#

Mon, 01 Jan 0001 00:00:00 +0000

C# Client Generation#

Generate a typed C# client from your deployment’s /openapi.json.

NSwag#

NSwag generates C# clients with full async support. Install via dotnet tool or NuGet.

dotnet tool install -g NSwag.ConsoleCore

# Generate client
nswag openapi2csclient \
 /input:http://localhost:3000/openapi.json \
 /output:ApiClient.cs \
 /namespace:MyProject.Api \
 /generateClientClasses:true \
 /generateDtoTypes:true

Usage:

using var httpClient = new HttpClient { BaseAddress = new Uri("http://localhost:3000") };
var client = new ApiClient(httpClient);

var result = await client.HelloWorldAsync("World");
Console.WriteLine(result.Message);

MSBuild Integration#

Add to your .csproj for build-time generation:

Generic (any language)

Mon, 01 Jan 0001 00:00:00 +0000

Generic Client Generation (Any Language)#

The OpenAPI Generator project supports 50+ languages and frameworks. Use it when no language-specific tool is a better fit.

openapi-generator#

# Install via npm, Homebrew, or Docker
npm install -g @openapitools/openapi-generator-cli

# List available generators
openapi-generator-cli list

# Generate a client
openapi-generator-cli generate \
 -i http://localhost:3000/openapi.json \
 -g <generator-name> \
 -o ./generated-client

Common generators:

Generator	Language/Framework
`typescript-fetch`	TypeScript with Fetch API
`typescript-axios`	TypeScript with Axios
`go`	Go
`python`	Python
`csharp`	C#
`java`	Java
`kotlin`	Kotlin
`rust`	Rust
`swift5`	Swift
`dart`	Dart/Flutter
`ruby`	Ruby
`php`	PHP

Docker (no local install)#

docker run --rm --network host \
 -v "${PWD}:/out" \
 openapitools/openapi-generator-cli generate \
 -i http://host.docker.internal:3000/openapi.json \
 -g typescript-fetch \
 -o /out/generated

Configuration#

Customize generation with a config file:

HTTP collections

Mon, 01 Jan 0001 00:00:00 +0000

HTTP Collections#

For ad-hoc API exploration without codegen, generate importable request files from /openapi.json.

VS Code REST Client (.http files)#

Generate .http files from the spec using jq:

curl -s http://localhost:3000/openapi.json | jq -r '
 .paths | to_entries[] | .key as $path |
 .value | to_entries[] |
 "\(.key | ascii_upcase) http://localhost:3000\($path)\n\n###\n"
' > api-requests.http

Open api-requests.http in VS Code with the REST Client extension. Click “Send Request” above any block.