# Client Code Generation

> [!note] Tato stránka ještě není přeložena do češtiny a zobrazuje se anglicky.


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](https://openapi-generator.tech/docs/generators).

## Getting the OpenAPI Specification

### 1. Access Swagger UI

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

> [!note] Replace localhost:42042 with your actual server address and port.</note>

### 2. Download swagger.json

The OpenAPI specification is available in JSON format at:\
[http://localhost:42042/swagger/v1/swagger.json](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

### Method 1: Using Docker (Recommended)

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

#### Basic Usage

```bash
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:**
```bash
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:**
```bash
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:**
```bash
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.
```bash
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:**
```powershell
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.
```bash
# 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](https://openapi-generator.tech/docs/generators)

### Documentation
- **html2** - HTML documentation
- **markdown** - Markdown documentation

## Automation Scripts

### Bash Script for Multiple Languages

Create a script `generate-clients.sh`:

```bash
#!/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`:

```powershell
# 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
```yaml
# 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**
```bash
# Validate your OpenAPI spec
docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli validate \
  -i /local/swagger.json
```

**Generator-Specific Issues:**
- Check the [OpenAPI Generator documentation](https://openapi-generator.tech/docs/generators) for generator-specific options
- Use `--help` flag to see available options for each generator

### Getting Help
- Review available generators: https://openapi-generator.tech/docs/generators
- Check configuration options: https://openapi-generator.tech/docs/configuration
- Community support: https://github.com/OpenAPITools/openapi-generator/issues