Auto-generates API clients from OpenAPI: single-file TypeScript client with Zod runtime validation, plus generated client libraries with configurable HTTP client and serialization support.
This project generates API clients from the OpenAPI specification for both Kotlin Multiplatform and TypeScript/Node.js applications.
hex-specs/
├── openApi/
│ └── hex-tractor-open-api.yml # OpenAPI specification
├── generated/ # Generated code (gitignored)
│ ├── kotlin/ # Generated Kotlin sources
│ └── typescript/ # Generated TypeScript sources
├── dist/
├── pom.xml
├── package.json
├── tsconfig.json
├── PUBLISHING.md
├── OPENAPI_ZOD_CLIENT.md
├── CHANGELOG.md
└── README.md
This project is published to both npm and Maven Central:
For publishing your own version, see PUBLISHING.md for complete setup instructions.
mvn clean generate-sources
This will generate Kotlin client code in the generated/kotlin directory with the following packages:
com.hextractor.api - API interfacescom.hextractor.api.model - Data modelscom.hextractor.api.client - Client infrastructuremvn clean package
This will compile the generated Kotlin code and create a JAR file in the target directory.
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")
}
import com.hextractor.api.client.ApiClient
import com.hextractor.api.AccountApi
import io.ktor.client.*
import io.ktor.client.engine.cio.*
{
client = HttpClient(CIO)
apiClient = ApiClient(basePath = , httpClient = client)
accountApi = AccountApi(apiClient)
{
account = accountApi.accountRegionSummonerNameTagLineGet(
region = ,
summonerName = ,
tagLine =
)
println()
} {
client.close()
}
}
The TypeScript client is generated with openapi-zod-client, providing runtime validation of API requests and responses using Zod schemas. This gives you:
See OPENAPI_ZOD_CLIENT.md for detailed documentation.
npm install
npm run generate
This will generate a TypeScript client with Zod schemas in generated/typescript/api.ts.
npm run build
This will:
dist directorynpm run clean
You can use the generated client in several ways:
# In the hex-specs directory
npm link
# In your Node.js project
npm link @hextractor/api-client
npm install path/to/hex-specs
npm publish
The Kotlin client is configured in pom.xml. Key settings:
The TypeScript client is configured in package.json. Key features:
openapi-zod-client (runtime validation)generated/typescript/api.ts)See OPENAPI_ZOD_CLIENT.md for detailed documentation on using the Zod-based client.
Edit pom.xml in the openapi-generator-maven-plugin configuration section to change:
Edit the generate script in package.json to change:
-o flag)See the openapi-zod-client documentation for all available options.
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
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
The generated clients provide access to the following endpoints:
Refer to hex-tractor-open-api.yml for detailed API documentation.
MIT
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();
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);
});
kotlin (multiplatform support)multiplatform (works with JVM, JS, and Native)kotlinx_serializationcom.hextractor.apicom.hextractor.api.modelcom.hextractor.api.clientSurfaced from shared tags and platforms — no rankings paid for.