Hex-Tractor API Client Generation

This project generates API clients from the OpenAPI specification for both Kotlin Multiplatform and TypeScript/Node.js applications.

Prerequisites

For Kotlin Generation

• Java 11 or higher
• Maven 3.6 or higher

For TypeScript Generation

• Node.js 18 or higher
• npm 9 or higher

Project Structure

hex-specs/
├── openApi/
│   └── hex-tractor-open-api.yml          # OpenAPI specification
├── generated/                             # Generated code (gitignored)
│   ├── kotlin/                            # Generated Kotlin sources
│   └── typescript/                        # Generated TypeScript sources
├── dist/                                  # Compiled TypeScript (gitignored)
├── pom.xml                                # Maven configuration
├── package.json                           # npm configuration
├── tsconfig.json                          # TypeScript configuration
├── PUBLISHING.md                          # Publishing guide
├── OPENAPI_ZOD_CLIENT.md                  # Zod client documentation
├── CHANGELOG.md                           # Version history
└── README.md                              # This file

📦 Published Packages

This project is published to both npm and Maven Central:

• npm: @hextractor/api-client
• Maven Central: com.hextractor:hex-tractor-api-client

For publishing your own version, see PUBLISHING.md for complete setup instructions.

Kotlin Multiplatform Client

Generate Kotlin Code

mvn clean generate-sources

This will generate Kotlin client code in the generated/kotlin directory with the following packages:

• com.hextractor.api - API interfaces
• com.hextractor.api.model - Data models
• com.hextractor.api.client - Client infrastructure

Build the Kotlin Library

mvn clean package

This will compile the generated Kotlin code and create a JAR file in the target directory.

Using in Your Kotlin Multiplatform Project

Add the generated library as a dependency in your build.gradle.kts:

dependencies {
    implementation(files("path/to/hex-tractor-api-client-1.0.0.jar"))
    
    // Required dependencies
    implementation("io.ktor:ktor-client-core:2.3.7")
    implementation("io.ktor:ktor-client-content-negotiation:2.3.7")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.7")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.2")
}

Or publish to your local Maven repository:

mvn clean install

Then add as a regular Maven dependency:

dependencies {
    implementation("com.hextractor:hex-tractor-api-client:1.0.0")
}

Example Kotlin Usage

import com.hextractor.api.client.ApiClient
import com.hextractor.api.AccountApi
import io.ktor.client.*
import io.ktor.client.engine.cio.*

suspend fun main() {
    val client = HttpClient(CIO)
    val apiClient = ApiClient(basePath = "http://localhost:3000/api", httpClient = client)
    val accountApi = AccountApi(apiClient)
    
    try {
        val account = accountApi.accountRegionSummonerNameTagLineGet(
            region = "euw1",
            summonerName = "PlayerName",
            tagLine = "EUW"
        )
        println("Account: $account")
    } finally {
        client.close()
    }
}

TypeScript/Node.js Client

The TypeScript client is generated with openapi-zod-client, providing runtime validation of API requests and responses using Zod schemas. This gives you:

• ✅ Runtime type safety with Zod validation
• ✅ Compile-time type safety with TypeScript
• ✅ Smaller bundle size (single file output)
• ✅ Better developer experience with automatic schema validation

See OPENAPI_ZOD_CLIENT.md for detailed documentation.

Install Dependencies

npm install

Generate TypeScript Code

npm run generate

This will generate a TypeScript client with Zod schemas in generated/typescript/api.ts.

Build the TypeScript Library

npm run build

This will:

1. Generate the TypeScript client with Zod schemas from the OpenAPI spec
2. Compile the TypeScript to JavaScript
3. Create type definitions
4. Output everything to the dist directory

Clean Generated Files

npm run clean

Using in Your Node.js/TypeScript Project

You can use the generated client in several ways:

Option 1: Link Locally During Development

# In the hex-specs directory
npm link

# In your Node.js project
npm link @hextractor/api-client

Option 2: Install from File

npm install path/to/hex-specs

Option 3: Publish to npm Registry

npm publish

Example TypeScript Usage

import { makeApi } from '@hextractor/api-client';
import Axios from 'axios';

// Create axios instance with base URL
const axios = Axios.create({ 
  baseURL: 'http://localhost:3000/api' 
});

// Create type-safe API client
const api = makeApi(axios);

async function getAccountInfo() {
  try {
    // All requests and responses are validated with Zod schemas
    const account = await api.accountRegionSummonerNameTagLineGet({
      params: {
        region: 'euw1',
        summonerName: 'PlayerName',
        tagLine: 'EUW'
      }
    });
    console.log('Account:', account);
    
    const matches = await api.matchesRegionPuuidGet({
      params: {
        region: 'euw1',
        puuid: account.generalInfo.puuid,
        start: 0,
        count: 10
      }
    });
    console.log('Matches:', matches);
  } catch (error) {
    // Zod validation errors or API errors
    console.error('Error:', error);
  }
}

getAccountInfo();

Example JavaScript Usage (CommonJS)

const { makeApi } = require('@hextractor/api-client');
const Axios = require('axios');

const axios = Axios.create({ 
  baseURL: 'http://localhost:3000/api' 
});

const api = makeApi(axios);

api.accountRegionSummonerNameTagLineGet({
  params: {
    region: 'euw1',
    summonerName: 'PlayerName',
    tagLine: 'EUW'
  }
})
  .then(account => {
    console.log('Account:', account);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Configuration

Kotlin Configuration

The Kotlin client is configured in pom.xml. Key settings:

• Generator: kotlin (multiplatform support)
• Library: multiplatform (works with JVM, JS, and Native)
• Serialization: kotlinx_serialization
• HTTP Client: Ktor
• Packages:
  • API: com.hextractor.api
  • Models: com.hextractor.api.model
  • Invoker: com.hextractor.api.client

TypeScript Configuration

The TypeScript client is configured in package.json. Key features:

• Generator: openapi-zod-client (runtime validation)
• Validation: Zod schemas for runtime type checking
• HTTP Client: Axios (you provide your own instance)
• Output: Single file (generated/typescript/api.ts)
• TypeScript: Strict mode with ES2020 target

See OPENAPI_ZOD_CLIENT.md for detailed documentation on using the Zod-based client.

Customization

Modify Kotlin Generation

Edit pom.xml in the openapi-generator-maven-plugin configuration section to change:

• Package names
• Output directory
• Generator options
• Dependencies

Modify TypeScript Generation

Edit the generate script in package.json to change:

• Output file location (-o flag)
• Additional openapi-zod-client options

See the openapi-zod-client documentation for all available options.

Troubleshooting

Kotlin Issues

Problem: Build fails with serialization errors

# Solution: Ensure kotlinx-serialization plugin is properly configured
mvn clean compile

Problem: Multiplatform compatibility issues

# Solution: Check that your target platform is supported by Ktor
# Update library version in pom.xml if needed

TypeScript Issues

Problem: Module not found errors

# Solution: Regenerate and rebuild
npm run clean
npm run build

Problem: Type definition errors

# Solution: Check tsconfig.json and ensure all paths are correct
npm install
npm run build

API Endpoints

The generated clients provide access to the following endpoints:

• Account API: Get Riot account information by summoner name/tag or PUUID
• Leagues API: Get league entries by queue, tier, and division
• Matches API: Get match details and match IDs by PUUID or match ID

Refer to hex-tractor-open-api.yml for detailed API documentation.

License

MIT