Skip to content

Generating a Client with OpenAPI Generator

The EU CAPTCHA verification API is described by a machine-readable OpenAPI 3.1 specification. You can use openapi-generator-cli to generate a native client library in any supported language directly from that spec — no manual HTTP wiring required.

Spec URL: https://docs-api.eu-captcha.eu/openapi.yaml

The official Java client variants were produced exactly this way.

Install openapi-generator-cli

Pick whichever method fits your toolchain:

npm (recommended for most projects):

npm install @openapitools/openapi-generator-cli -g

Homebrew (macOS / Linux):

brew install openapi-generator
# use `openapi-generator` instead of `openapi-generator-cli` in the commands below

JAR (no package manager required):

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.18.0/openapi-generator-cli-7.18.0.jar \
     -O openapi-generator-cli.jar
# then: java -jar openapi-generator-cli.jar generate ...

Basic command

openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g <generator> \
  -o ./eu-captcha-client
Flag Description
-i Input spec — URL or local file path
-g Generator name (see examples below)
-o Output directory for the generated project
--additional-properties Comma-separated key=value pairs passed to the generator

List all available generators:

openapi-generator-cli list

Language examples

TypeScript (fetch)

openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g typescript-fetch \
  -o ./eu-captcha-client \
  --additional-properties=npmName=eu-captcha-client,supportsES6=true

Go

openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g go \
  -o ./eu-captcha-client \
  --additional-properties=packageName=eucaptcha

Ruby

openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g ruby \
  -o ./eu-captcha-client \
  --additional-properties=gemName=eu_captcha

C# (.NET)

openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g csharp \
  -o ./eu-captcha-client \
  --additional-properties=packageName=EuCaptcha

Kotlin

openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g kotlin \
  -o ./eu-captcha-client \
  --additional-properties=groupId=com.myrasec,artifactId=eu-captcha-client

Official Java variants

The commands below reproduce the three pre-built variants in the Java client exactly:

# Spring RestTemplate (Java 17+, Spring Framework 6 / WebMVC)
openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g java \
  -o ./java-resttemplate \
  --additional-properties=packageName=eucaptcha,groupId=com.myrasec,\
invokerPackage=com.myrasec.client,apiPackage=com.myrasec.client.api,\
modelPackage=com.myrasec.client.model,library=resttemplate

# Spring WebClient (Java 8+, Spring Boot 2 / WebFlux)
openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g java \
  -o ./java-webflux-boot2 \
  --additional-properties=packageName=eucaptcha,groupId=com.myrasec,\
invokerPackage=com.myrasec.client,apiPackage=com.myrasec.client.api,\
modelPackage=com.myrasec.client.model,library=webclient

# Spring Boot 3 / Jakarta EE (Java 17+)
openapi-generator-cli generate \
  -i https://docs-api.eu-captcha.eu/openapi.yaml \
  -g java \
  -o ./java-webflux-boot3 \
  --additional-properties=packageName=eucaptcha,groupId=com.myrasec,\
invokerPackage=com.myrasec.client,apiPackage=com.myrasec.client.api,\
modelPackage=com.myrasec.client.model,library=webclient,\
useSpringBoot3=true,useJakartaEe=true

What gets generated

Regardless of language, the generator produces:

  • An API class (EuCaptchaApi / VerificationApi) with a single method wrapping POST /verify
  • A request model (VerifyRequest) with fields for all five required parameters
  • A response model (VerifyResponse) with success and train fields
  • HTTP client wiring, serialisation, and error handling boilerplate
  • A build file (pom.xml, go.mod, package.json, etc.) and a generated README

Always check train

The generated VerifyResponse exposes both fields from the API response. Your code must check train in addition to success — when train is true, validation was bypassed and all tokens appear valid regardless of their actual state. See Server-Side Verification for details.

Further reading