# Client Code Generation

> [!note] 이 페이지는 아직 한국어로 번역되지 않아 영어로 표시됩니다.


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