Code Generation

GoRoute provides an OpenAPI specification that you can use to generate client code in virtually any programming language. GoRoute does not publish official client libraries, so generating a client from the specification is the supported way to work with the API in a typed language.

OpenAPI Specification

Generate from this address:

https://docs.goroute.ai/openapi/goroute-api.json

It is an OpenAPI 3.1 document in JSON, it is the same description this site's API Reference is built from, and it is refreshed whenever that reference is regenerated. It covers the 277 documented paths of the GoRoute API — 324 operations in all.

JSON is the only format published. There is no YAML version. Both OpenAPI Generator and Postman read JSON, so nothing below needs one.

If you built against app.goroute.ai/peppol-api/openapi.json, it has stopped answering

Until this page was corrected it sent you to https://app.goroute.ai/peppol-api/openapi.json for the description, and offered a YAML companion alongside it. On 19 September 2026 the production service answered 404 at both addresses — and the YAML one has never existed on any GoRoute service. A build pipeline that fetches either will fail rather than warn.

Point it at https://docs.goroute.ai/openapi/goroute-api.json instead. Nothing else about your generated client changes: the API base URL you call at run time is still https://app.goroute.ai/peppol-api.

Using OpenAPI Generator

OpenAPI Generator supports 50+ languages and frameworks.

Installation

# npm
npm install @openapitools/openapi-generator-cli -g

# Homebrew (macOS)
brew install openapi-generator

# Docker
docker pull openapitools/openapi-generator-cli

Generate a Client

# Python
openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g python \
  -o ./goroute-python-client

# TypeScript (Axios)
openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g typescript-axios \
  -o ./goroute-ts-client

# C#
openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g csharp \
  -o ./goroute-csharp-client

# Go
openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g go \
  -o ./goroute-go-client

# Ruby
openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g ruby \
  -o ./goroute-ruby-client

Using Docker

docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g python \
  -o /local/goroute-python-client

Using Swagger Codegen

Swagger Codegen is the original code generator.

Installation

# Homebrew
brew install swagger-codegen

# Download JAR
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.52/swagger-codegen-cli-3.0.52.jar

Generate a Client

swagger-codegen generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -l python \
  -o ./goroute-python-client

Language-Specific Examples

Python (with async support)

openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g python \
  -o ./client \
  --additional-properties=asyncio=true,packageName=goroute_client

Usage:

from goroute_client import ApiClient, Configuration, DocumentsApi

config = Configuration(
    host="https://app.goroute.ai/peppol-api",
    api_key={"X-API-Key": "your-api-key"}
)

async with ApiClient(config) as api_client:
    documents_api = DocumentsApi(api_client)
    result = await documents_api.send_document(document_request)

TypeScript (Fetch API)

openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g typescript-fetch \
  -o ./client \
  --additional-properties=npmName=goroute-client,supportsES6=true

Usage:

import { Configuration, DocumentsApi } from './client';

const config = new Configuration({
  basePath: 'https://app.goroute.ai/peppol-api',
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

const documentsApi = new DocumentsApi(config);
const result = await documentsApi.sendDocument({ ... });

Go

openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g go \
  -o ./client \
  --additional-properties=packageName=goroute

Usage:

package main

import (
    "context"
    "github.com/yourorg/goroute"
)

func main() {
    config := goroute.NewConfiguration()
    config.AddDefaultHeader("X-API-Key", "your-api-key")
    
    client := goroute.NewAPIClient(config)
    
    result, _, err := client.DocumentsApi.SendDocument(context.Background()).Execute()
    if err != nil {
        panic(err)
    }
}

PHP

openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g php \
  -o ./client \
  --additional-properties=invokerPackage=GoRoute\\Peppol

Usage:

<?php
require_once 'vendor/autoload.php';

$config = GoRoute\Peppol\Configuration::getDefaultConfiguration()
    ->setApiKey('X-API-Key', 'your-api-key');

$apiInstance = new GoRoute\Peppol\Api\DocumentsApi(
    new GuzzleHttp\Client(),
    $config
);

$result = $apiInstance->sendDocument($request);

Customizing Generated Code

Custom Templates

You can customize the generated code using templates:

# Export default templates
openapi-generator-cli author template -g python -o ./templates

# Generate with custom templates
openapi-generator-cli generate \
  -i https://docs.goroute.ai/openapi/goroute-api.json \
  -g python \
  -o ./client \
  -t ./templates

Configuration File

Create an openapi-generator-config.yaml:

generatorName: python
outputDir: ./client
inputSpec: https://docs.goroute.ai/openapi/goroute-api.json
additionalProperties:
  packageName: goroute_client
  projectName: goroute-peppol
  asyncio: true
  generateSourceCodeOnly: true

Run with:

openapi-generator-cli generate -c openapi-generator-config.yaml

Supported Generators

Language	Generator Name	Notes
Python	python	Includes async support
TypeScript	typescript-axios, typescript-fetch	Multiple HTTP client options
JavaScript	javascript	ES6+ support
C#	csharp, csharp-netcore	.NET Framework & Core
Java	java	Multiple HTTP client options
Go	go	Standard library HTTP
Ruby	ruby	Faraday HTTP client
PHP	php	Guzzle HTTP client
Kotlin	kotlin	Coroutines support
Swift	swift5	iOS/macOS
Rust	rust	Hyper/Reqwest

Full list: OpenAPI Generator Docs

Best Practices

1. Build From a Copy You Keep

There is no versioned copy of the description to pin to — /v1/openapi.json and the like do not exist, on any GoRoute service. What you can do instead is keep the exact file you generated from:

# Save the description you generated from, and commit it
curl -s https://docs.goroute.ai/openapi/goroute-api.json -o openapi-cache.json

openapi-generator-cli generate \
  -i ./openapi-cache.json \
  -g python \
  -o ./client

Your build is then repeatable, and you can see exactly what changed before you regenerate — see Keep Generated Code Updated below.

2. Add Error Handling

Generated clients provide basic error handling. Add retry logic:

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
def send_with_retry(client, document):
    return client.documents_api.send_document(document)

3. Validate Before Sending

Always validate documents before sending:

# Validate first
validation = client.documents_api.validate_document(document)
if not validation.valid:
    raise ValueError(f"Invalid document: {validation.errors}")

# Then send
result = client.documents_api.send_document(document)

4. Keep Generated Code Updated

When we release API updates, regenerate your client:

# Check for changes against the copy you built from
diff <(curl -s https://docs.goroute.ai/openapi/goroute-api.json) ./openapi-cache.json

# Regenerate if changed, then refresh the cached copy
openapi-generator-cli generate ...
curl -s https://docs.goroute.ai/openapi/goroute-api.json -o openapi-cache.json

Troubleshooting

Generated Code Won't Compile

Solution: Ensure you're using a compatible generator version:

openapi-generator-cli version-manager set 7.0.0

Missing Authentication

Solution: Manually add the API key header if not automatically included:

config.api_key['X-API-Key'] = 'your-api-key'

Type Errors

Solution: Some generators create strict types. Use Any or disable strict mode:

--additional-properties=strictSpec=false

Resources

• OpenAPI Generator Documentation
• Swagger Codegen GitHub
• OpenAPI 3.0 Specification