# Generate a Java SDK from OpenAPI / Swagger
Source: https://speakeasy.com/docs/sdks/languages/java/methodology-java

import { FileTree } from "nextra/components";



## Overview

Speakeasy generates Java SDKs that integrate naturally with existing Java ecosystems, following established conventions for consistency with hand-written libraries. The generated code provides full IDE support, compile-time validation, and seamless integration with standard tooling.

**Design principles:**
- **Native Java ergonomics**: Code generation leverages Java's type system, generics, and method chaining to create APIs that feel natural to Java developers. Builder patterns, fluent interfaces, and standard library types eliminate the need to learn framework-specific abstractions
- **Comprehensive type safety**: Strong typing catches API contract violations at compile time, while JSR-305/Jakarta nullability annotations provide rich IDE warnings and autocomplete derived directly from your OpenAPI specification
- **Flexible concurrency models**: Synchronous execution by default supports traditional blocking patterns, while `.async()` mode provides `CompletableFuture<T>` and reactive streams support for non-blocking architectures—enabling incremental adoption without rewriting existing code
- **Minimal runtime dependencies**: Built on Java standard library primitives like `CompletableFuture<T>` and `Flow.Publisher<T>` rather than heavyweight frameworks, ensuring clean integration into existing codebases and microservice architectures
- **Built-in observability**: SLF4J integration provides structured logging across all SDK operations without framework lock-in, enabling comprehensive monitoring of HTTP requests, retries, streaming, and hook execution
- **Specification fidelity**: Method signatures, documentation, and validation rules generated directly from OpenAPI definitions maintain accuracy between API contracts and client code, reducing integration surprises

```java
// Initialize SDK with builder pattern - idiomatic Java design
SDK sdk = SDK.builder()
    .serverURL("https://api.example.com")
    .apiKey("your-api-key")
    .build();

// Type-safe method chaining with IDE autocomplete
User user = sdk.users()
    .userId("user-123")                    // Required field - compile-time safety
    .includeMetadata(true)                 // Optional field - null-friendly
    .call();                               // Synchronous by default

// Seamless async with same API - just add .async()
CompletableFuture<User> asyncUser = sdk.async().users()
    .userId("user-123")
    .includeMetadata(true)
    .call();

// Native reactive streams support
Publisher<Order> orderStream = sdk.async().orders()
    .status("active")
    .callAsPublisher();

// Pagination with familiar Java patterns
sdk.orders()
    .status("completed")
    .callAsStream()                        // Returns java.util.Stream
    .filter(order -> order.amount() > 100)
    .limit(50)
    .forEach(System.out::println);

// Rich exception handling with context
try {
    User result = sdk.users().userId("invalid").call();
} catch (APIException e) {
    // Detailed error context from OpenAPI spec
    System.err.println("API Error: " + e.getMessage());
    System.err.println("Status: " + e.statusCode());
}
```

## Core Features

### Type Safety & Null Handling

The SDK provides compile-time validation and runtime checks for required fields, with intuitive null handling:

- **Compile-time validation**: Strong typing catches problems before runtime
- **Runtime validation**: Required fields throw exceptions if missing
- **Null-friendly setters**: Simple setters without Optional/JsonNullable wrapping
- **Smart getters**: Return types match field semantics - direct access for required fields, `Optional<T>` for non-required fields, and [`JsonNullable<T>`](https://github.com/OpenAPITools/jackson-databind-nullable) for non-required nullable fields

```java
// Builder with various field types
User user = User.builder()
    .id(123L)                           // Required primitive
    .name("John Doe")                   // Required string
    .email("john@example.com")          // Required field
    .age(30)                           // Optional primitive - defaults if not set
    .bio("Developer")                   // Optional string - can be null
    .profileImage(null)                 // Nullable field - accepts null explicitly
    .build();                           // Throws runtime exception if required fields missing

// Type-safe getters with semantically appropriate return types
String name = user.name();                    // Direct access for required fields
Optional<Integer> age = user.age();           // Optional for non-required fields
JsonNullable<String> bio = user.bio();        // JsonNullable for non-required + nullable fields

// Method chaining with runtime validation
CreateUserRequest request = CreateUserRequest.builder()
    .user(user)                         // Required - runtime exception if missing
    .sendWelcomeEmail(true)             // Optional boolean
    .metadata(Map.of("source", "api"))  // Optional complex type
    .build();                           // Validates all required fields
```

### Fluent Call-Builder Chaining

The SDK supports fluent method chaining that combines method builders with request builders for intuitive API calls:

```java
// Fluent chaining: method builder → parameters → request body → call
User res = sdk.updateUser()
        .id("user-123")                                // Path/query parameters
        .payload(PatchUser.builder()
            .name("John Doe")                          // Request body fields
            .email("john@example.com")
            .build())
        .call();                                       // Execute request
```

### Authentication & Security

- OAuth flows and standard security mechanisms
- Custom enum types using string or integer values
- All-field constructors for compile-time OpenAPI change detection

## Synchronous Methods

### Basic Methods

Synchronous methods are the default mode for all SDK calls:

```java
// Standard synchronous calls
Portfolio portfolio = sdk.getPortfolio("user-123");
List<Trade> trades = sdk.getTrades(portfolio.getId());
```

### Pagination

For synchronous pagination, use `.call()`, `.callAsIterable()`, `.callAsStream()`, or `.callAsStreamUnwrapped()`:

- **`.call()`**: Returns the first page only
- **`.callAsIterable()`**: Returns `Iterable<>` for for-each iteration with automatic paging
- **`.callAsStream()`**: Returns `java.util.Stream` of pages with automatic paging
- **`.callAsStreamUnwrapped()`**: Returns `java.util.Stream` of concatenated items from all pages

```java
// Stream unwrapped example
sdk.searchDocuments()
   .contains("simple")
   .minSize(200)
   .maxSize(400)
   .callAsStreamUnwrapped()  // Returns Stream<Document>
   .filter(document -> "fiction".equals(document.category()))
   .limit(200)
   .forEach(System.out::println);
```

### Server-Sent Events

For synchronous SSE, use the `events()` method with try-with-resources:

```java
// Traverse event stream with while loop
try (EventStream<JsonEvent> events = response.events()) {
    Optional<JsonEvent> event;
    while ((event = events.next()).isPresent()) {
        processEvent(event.get());
    }
}

// Use with java.util.Stream
try (EventStream<JsonEvent> events = response.events()) {
    events.stream().forEach(this::processEvent);
}
```

### Error Handling

The SDK throws typed unchecked exceptions for all errors, organized in a hierarchy:

```
Base SDK Error
├── Default SDK Error (for network/IO errors and untyped API errors)
├── Default Async SDK Error (for async-specific errors)
└── Custom Errors (for typed error responses defined in OpenAPI spec)
```

Error class names can be customized via `gen.yaml` flags; if not specified, they're inferred from the SDK name.

#### Base SDK Error

All exceptions extend `RuntimeException` and encapsulate the raw HTTP response with accessors for:
- **Status code**: `statusCode()`
- **Headers**: `headers()`
- **Body**: `body()` returns `Optional<byte[]>` and `bodyAsString()` returns `Optional<String>` (accounts for cases where the body couldn't be read due to `IOException`)

#### Default SDK Error

The default SDK error is thrown during:
- **Network/IO errors**: Connection failures, timeouts, and other transport-level issues
- **Untyped API errors**: HTTP error responses without custom error schemas defined in the OpenAPI spec

#### Custom Error Responses

For operations with error responses defined in the OpenAPI spec, the SDK generates typed exception classes that encapsulate the error schema.

**Example OpenAPI spec:**
```yaml
paths:
  /users/{userId}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserError'
components:
  schemas:
    UserError:
      type: object
      properties:
        code:
          type: string
          enum: [NotFound, Unauthorized]
        reason:
          type: string
```

**Generated exception class:**
```java
public class UserError extends BaseSdkError {
    // Error schema as nested static class
    public static class Data {
        // Generated enum from OpenAPI spec
        public enum Code {
            NOT_FOUND("NotFound"),
            UNAUTHORIZED("Unauthorized");

            private final String value;
            Code(String value) { this.value = value; }
            public String value() { return value; }
        }

        private Code code;
        private String reason;
        // Getters and setters...
    }

    // Hoisted field accessors for convenience
    public Optional<Data.Code> code() { ... }
    public Optional<String> reason() { ... }

    // Full error object accessor
    public Optional<Data> data() { ... }

    // Available if deserialization failed
    public Optional<IOException> deserializationError() { ... }
}
```

All accessors return `Optional` to handle cases where the response body couldn't be deserialized.

**Usage:**
```java
try {
    User user = sdk.getUser("user-123");
} catch (UserError e) {
    // Handle typed error with field access
    e.code().ifPresent(code ->
        System.err.println("Error Code: " + code));
    e.reason().ifPresent(reason ->
        System.err.println("Reason: " + reason));

    // Check for deserialization issues
    if (e.deserializationError().isPresent()) {
        System.err.println("Failed to parse error response");
    }
} catch (SDKError e) {
    // Handle default SDK errors (network issues, untyped errors)
    System.err.println("Request failed: " + e.getMessage());
    System.err.println("Status: " + e.statusCode());
}
```

## Asynchronous Methods

### Dual SDK Architecture

Speakeasy Java SDKs implement a dual interface pattern that provides both synchronous and asynchronous programming models without breaking changes:

- **Synchronous by default**: All SDK instances work synchronously out of the box, maintaining compatibility with existing code.
- **Async opt-in**: Call `.async()` on any SDK instance to switch to asynchronous mode for that method chain.
- **Consistent API**: The same methods and parameters work in both modes, only the return types differ.

```java
// Single SDK instance serves both paradigms
TradingSDK sdk = TradingSDK.builder()
    .serverURL("https://api.example.com")
    .apiKey("your-api-key")
    .build();

// Synchronous usage
Portfolio portfolio = sdk.getPortfolio("user-123");
List<Trade> trades = sdk.getTrades(portfolio.getId());

// Asynchronous usage
CompletableFuture<Portfolio> asyncPortfolio = sdk.async()
    .getPortfolio("user-123");
CompletableFuture<List<Trade>> asyncTrades = asyncPortfolio
    .thenCompose(p -> 
        sdk.async().getTrades(p.getId()));
```

### Non-blocking I/O implementation

The async implementation uses Java 11's `HttpClient` async APIs and NIO.2 primitives for end-to-end non-blocking method calls:

- **HTTP requests**: `HttpClient.sendAsync()` with `CompletableFuture<HttpResponse<T>>`
- **File I/O**: `AsynchronousFileChannel` for non-blocking file methods
- **Stream processing**: `Flow.Publisher<List<ByteBuffer>>` for efficient byte handling

```java
// Underlying HTTP implementation
client.sendAsync(request, HttpResponse.BodyHandlers.ofPublisher())
    .thenApply(response -> response.body()) // Flow.Publisher<List<ByteBuffer>>
    .thenCompose(this::decodeJsonAsync);
```

### Reactive Streams integration

For async iterables, the SDK leverages [Reactive Streams](https://www.reactive-streams.org/) `Publisher<T>` to provide:

- **Backpressure handling**: Consumers control the rate of data processing
- **Ecosystem interoperability**: Works with [Project Reactor](https://projectreactor.io/), RxJava, Akka Streams, and other reactive libraries
- **Resource efficiency**: Memory-efficient processing of large datasets
- **Composition**: Chain and transform async streams declaratively

The examples in this documentation use `Flux` from [Project Reactor](https://projectreactor.io/) to demonstrate interoperability with reactive frameworks.

The SDK implements custom publishers, subscribers, and subscriptions using JDK-native operators while maintaining lightweight dependencies.

### Async Pagination

For async pagination, use `callAsPublisher()` and `callAsPublisherUnwrapped()` methods that return reactive streams:

```java
// Async pagination - returns Publisher<PageResponse>
Publisher<UserPageResponse> userPages = sdk.async().listUsers()
    .callAsPublisher();

// Async pagination unwrapped - returns Publisher<User> (concatenated items)
Publisher<User> users = sdk.async().listUsers()
    .callAsPublisherUnwrapped();

// Use with reactive libraries (Flux is from Project Reactor)
Flux.from(users)
    .filter(User::isActive)
    .take(100)
    .subscribe(this::processUser);
```

### Async Server-Sent Events

For async SSE, `EventStream` implements `Publisher<EventType>` directly:

```java
// Async SSE streaming - EventStream implements Publisher and handles async response
EventStream<LogEvent> eventStream = sdk.async().streamLogs().events();

// Process with reactive libraries - EventStream is a Publisher
Flux.from(eventStream)
    .filter(event -> "ERROR".equals(event.getLevel()))
    .subscribe(this::handleErrorEvent);
```

### Migration & DevX Improvements

Async-enabled SDKs provide backward compatibility, gradual adoption via `.async()` calls, and compatibility with Java 21+ virtual threads. Additional enhancements include null-friendly parameters, Jakarta annotations, enhanced error handling, and built-in timeout/cancellation support.

### Package Structure

<FileTree>
  <FileTree.File name="build.gradle" />
  <FileTree.File name="build-extras.gradle" />
  <FileTree.Folder name="src">
    <FileTree.Folder name="main">
      <FileTree.Folder name="{SDK Package Name}">
        <FileTree.File name="SDK.java" />
        <FileTree.File name="AsyncSDK.java" />
        <FileTree.File name="SDKConfiguration.java" />
        <FileTree.File name="SubSDK.java" />
        <FileTree.File name="AsyncSubSDK.java" />
        <FileTree.File name="..." />
        <FileTree.Folder name="models">
          <FileTree.Folder name="operations">
            <FileTree.File name="..." />
          </FileTree.Folder>
          <FileTree.Folder name="shared">
            <FileTree.File name="..." />
          </FileTree.Folder>
          <FileTree.Folder name="errors">
            <FileTree.File name="..." />
          </FileTree.Folder>
        </FileTree.Folder>
        <FileTree.Folder name="operations">
          <FileTree.File name="CreateUser.java" />
          <FileTree.File name="GetUser.java" />
          <FileTree.File name="PostFile.java" />
          <FileTree.File name="..." />
        </FileTree.Folder>
        <FileTree.Folder name="utils">
          <FileTree.File name="HTTPClient.java" />
          <FileTree.File name="Blob.java" />
          <FileTree.File name="EventStream.java" />
          <FileTree.File name="AsyncHooks.java" />
          <FileTree.File name="AsyncRetries.java" />
          <FileTree.Folder name="pagination">
            <FileTree.File name="..." />
          </FileTree.Folder>
          <FileTree.Folder name="reactive">
            <FileTree.File name="..." />
          </FileTree.Folder>
          <FileTree.File name="..." />
        </FileTree.Folder>
        <FileTree.Folder name="hooks">
          <FileTree.File name="SDKHooks.java" />
          <FileTree.File name="..." />
        </FileTree.Folder>
      </FileTree.Folder>
    </FileTree.Folder>
  </FileTree.Folder>
  <FileTree.Folder name="docs">
    <FileTree.File name="..." />
  </FileTree.Folder>
  <FileTree.File name="gradlew" />
  <FileTree.File name="settings.gradle" />
  <FileTree.File name="..." />
</FileTree>

## Advanced Topics

### Blob Abstraction

The `Blob` class provides efficient byte-stream handling across both sync and async methods:

```java
// Create from various sources
Blob.from(Paths.get("large-file.json"));    // File path
Blob.from(inputStream);                      // InputStream  
Blob.from("content");                        // String
Blob.from(publisherOfByteBuffers);          // Flow.Publisher

// Async consumption
CompletableFuture<byte[]> bytes = blob.toByteArray();
CompletableFuture<Path> path = blob.toFile(targetPath);
Publisher<ByteBuffer> stream = blob.asPublisher();
```

### HTTP Client Customization

The Java SDK HTTP client is configurable and supports both synchronous and asynchronous methods:

```java
public interface HTTPClient {
    HttpResponse<InputStream> send(HttpRequest request)
            throws IOException, InterruptedException, URISyntaxException;
      
    CompletableFuture<HttpResponse<Blob>> sendAsync(HttpRequest request);
}
```

A default implementation based on `java.net.HttpClient` provides sync and async patterns with connection pooling and streaming support.

### Custom Headers

Custom headers (those not explicitly defined in the OpenAPI spec) can be specified per-request using the call builder:
```java
CreatePaymentResponse res = sdk.payments().create()
    .paymentRequest(PaymentRequest.builder()
        .description("My first payment")
        .redirectUrl("https://example.org/redirect")
        .amount(10)
        .build())
    .header("IdempotencyKey", nextKey()) // custom header
    .call();
```
### Data Types & Serialization

The SDK uses native Java types where possible and provides custom handling for complex OpenAPI constructs.

#### Primitive and Native Types

Where possible, the Java SDK uses native types and primitives to increase null safety:

- `java.lang.String`
- `java.time.OffsetDateTime` for `date-time` format
- `java.time.LocalDate` for `date` format  
- `java.math.BigInteger` for unlimited-precision integers
- `java.math.BigDecimal` for unlimited-precision decimals
- `int` (or `java.lang.Integer`)
- `long` (or `java.lang.Long`)
- `float` (or `java.lang.Float`)
- `double` (or `java.lang.Double`)
- `boolean` (or `java.lang.Boolean`)

#### Unlimited-Precision Numerics

For applications requiring high-precision decimal or integer types (such as monetary amounts), use format specifications:

```yaml