Code Generation

GoRoute provides an OpenAPI 3.0 specification that you can use to generate client code in virtually any programming language. This is useful when you need a custom integration or use a language we don't have an official SDK for.

OpenAPI Specification

Our OpenAPI spec is available at:

• JSON: https://app.goroute.ai/peppol-api/openapi.json
• YAML: https://app.goroute.ai/peppol-api/openapi.yaml

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://app.goroute.ai/peppol-api/openapi.json \
  -g python \
  -o ./goroute-python-client

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

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

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

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

Using Docker

docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i https://app.goroute.ai/peppol-api/openapi.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://app.goroute.ai/peppol-api/openapi.json \
  -l python \
  -o ./goroute-python-client

Language-Specific Examples

Python (with async support)

openapi-generator-cli generate \
  -i https://app.goroute.ai/peppol-api/openapi.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://app.goroute.ai/peppol-api/openapi.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://app.goroute.ai/peppol-api/openapi.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://app.goroute.ai/peppol-api/openapi.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://app.goroute.ai/peppol-api/openapi.json \
  -g python \
  -o ./client \
  -t ./templates

Configuration File

Create an openapi-generator-config.yaml:

generatorName: python
outputDir: ./client
inputSpec: https://app.goroute.ai/peppol-api/openapi.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. Pin the Spec Version

Always use a versioned spec URL in production:

openapi-generator-cli generate \
  -i https://app.goroute.ai/peppol-api/v1/openapi.json \
  ...

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
diff <(curl -s https://app.goroute.ai/peppol-api/openapi.json) ./openapi-cache.json

# Regenerate if changed
openapi-generator-cli generate ...

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