Client Code Generation

This guide explains how to obtain the OpenAPI specification (swagger.json) from the Elements Hub API server and generate client code for various programming languages using OpenAPI Generator.

Getting the OpenAPI Specification

1. Access Swagger UI

The Elements Hub server provides an interactive Swagger UI interface accessible at:
http://localhost:42042/swagger/

Replace localhost:42042 with your actual server address and port.

2. Download swagger.json

The OpenAPI specification is available in JSON format at:
http://localhost:42042/swagger/v1/swagger.json

You can download this file using:

curl
curl -o swagger.json http://localhost:42042/swagger/v1/swagger.json

wget
wget -O swagger.json http://localhost:42042/swagger/v1/swagger.json

PowerShell
Invoke-WebRequest -Uri "http://localhost:42042/swagger/v1/swagger.json" -OutFile "swagger.json"

Client Code Generation with OpenAPI Generator

The easiest way to generate client code is using the official OpenAPI Generator Docker image.

Basic Usage
docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/swagger.json \
  -g "generator-name" \
  -o /local/out/generated-client \
  --additional-properties=your-additional-properties
Language-Specific Examples

C# Client:

docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/swagger.json \
  -g csharp \
  -o /local/generated-client-csharp \
  --additional-properties=apiName=RhopointElementsHubClient,packageName=Rhopoint.ElementsHub.Client,nullableReferenceTypes=true,targetFramework=net9.0

C++ Client:

docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/swagger.json \
  -g cpp-restsdk \
  -o /local/out/cpp-client \
  --additional-properties=apiPackage=com.rhopointinstruments.elementshub.api,modelPackage=com.rhopointinstruments.elementshub.model,packageName=RhopointHeadlessElements

Python Client:

docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/swagger.json \
  -g python \
  -o /local/generated-client-python \
  --additional-properties=packageName=rhopoint_elements_hub_client,projectName=rhopoint-elements-hub-client

**JavaScript/TypeScript Client:**
This example uses the Angular framework.

docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/swagger.json \
  -g typescript-angular \
  -o /local/generated-client-typescript \
  --additional-properties=npmName=rhopoint-elements-hub-client
PowerShell Examples (Windows)

C# Client:

docker run --rm `
  -v ${PWD}:/local `
  openapitools/openapi-generator-cli generate `
  -i /local/swagger.json `
  -g csharp `
  -o /local/generated-client-csharp `
  --additional-properties=apiName=RhopointElementsHubClient,packageName=Rhopoint.ElementsHub.Client,nullableReferenceTypes=true,targetFramework=net9.0

Method 2: Using NPM Package

You can also install and use the OpenAPI Generator via NPM.
This example uses the Angular framework.

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

## Generate client code
openapi-generator-cli generate \
  -i swagger.json \
  -g typescript-angular \
  -o generated-client-typescript

Supported Generators

OpenAPI Generator supports numerous programming languages and frameworks. Here are some popular options:

Client Libraries

  • csharp - C# client library
  • python - Python client library
  • java - Java client library
  • javascript - JavaScript client library
  • typescript-axios - TypeScript client with Axios
  • typescript-fetch - TypeScript client with Fetch API
  • go - Go client library
  • php - PHP client library
  • ruby - Ruby client library
  • swift5 - Swift 5 client library
  • kotlin - Kotlin client library
  • dart - Dart client library
  • more

Documentation

  • html2 - HTML documentation
  • markdown - Markdown documentation

Automation Scripts

Bash Script for Multiple Languages

Create a script generate-clients.sh:

#!/bin/bash

## Download latest OpenAPI spec
curl -o swagger.json http://localhost:42042/swagger/v1/swagger.json

## Generate clients for multiple languages
languages=("csharp" "cpp-client" "python" "typescript-angular" "java" "go")

for lang in "${languages[@]}"; do
    echo "Generating $lang client..."
    docker run --rm \
      -v ${PWD}:/local \
      openapitools/openapi-generator-cli generate \
      -i /local/swagger.json \
      -g $lang \
      -o /local/generated-client-$lang \
      --additional-properties=packageName=RhopointElementsHubClient
done

echo "Client generation completed."

PowerShell Script for Windows

Create a script Generate-Clients.ps1:

## Download latest OpenAPI spec
Invoke-WebRequest -Uri "http://localhost:42042/swagger/v1/swagger.json" -OutFile "swagger.json"

## Define languages to generate
$languages = @("csharp", "cpp-client", "python", "typescript-angular", "java", "go")

foreach ($lang in $languages) {
    Write-Host "Generating $lang client..."
    docker run --rm `
      -v ${PWD}:/local `
      openapitools/openapi-generator-cli generate `
      -i /local/swagger.json `
      -g $lang `
      -o /local/generated-client-$lang `
      --additional-properties=packageName=RhopointElementsHubClient
}

Write-Host "Client generation completed."

Best Practices

1. Version Control

  • Keep the swagger.json file in version control.
  • Generate clients as part of your build process.
  • Tag client versions to match API versions.
  • Use a wrapper project to better separate the generated client from your actual project.

2. CI/CD Integration

## Example GitHub Actions workflow
name: Generate API Clients
on:
  push:
    paths:
      - 'swagger.json'

jobs:
  generate-clients:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate C# Client
        run: |
          docker run --rm \
            -v ${PWD}:/local \
            openapitools/openapi-generator-cli generate \
            -i /local/swagger.json \
            -g csharp \
            -o /local/clients/csharp

3. Customization

  • Use custom templates when the default generation doesn't meet your needs
  • Validate generated code with your coding standards
  • Consider post-processing scripts for additional customization

Troubleshooting

Common Issues

Docker Volume Mounting:

  • On Windows, ensure Docker Desktop has access to the drive containing your files.
  • Use absolute paths if relative paths don't work.

OpenAPI Specification Validation

## Validate your OpenAPI spec
docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli validate \
  -i /local/swagger.json

Generator-Specific Issues:

Getting Help