Multiple Responses

When an OpenAPI operation defines multiple successful response codes with different schemas or content types, liblab generates an SDK method that returns a named response model. This model provides a clear, typed wrapper around the possible response variants while internally using a OneOf utility to manage the underlying union logic. This approach preserves type safety and keeps the complexity of the OneOf implementation hidden behind a straightforward, descriptive model.

Understanding Multiple Responses

APIs often return different response structures based on various conditions:

• Different content types (e.g., application/json vs application/xml)
• Different schemas for the same status code
• Different schemas for different successful status codes (e.g., 200 and 201)

liblab automatically detects these scenarios and generates appropriate OneOf return types that allow developers to handle each possible response type safely.

OpenAPI Schema Definition

Here's an example of an OpenAPI specification with multiple responses:

paths:
  /pet:
    get:
      tags:
        - pets
      operationId: getPet
      responses:
        '200':
          description: Returns either a cat or a dog.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Cat'
                  - $ref: '#/components/schemas/Dog'
components:
  schemas:
    Cat:
      type: object
      properties:
        species:
          type: string
          example: cat
        whiskerLength:
          type: number
        name:
          type: string
      required:
        - species
        - name
    Dog:
      type: object
      properties:
        species:
          type: string
          example: dog
        barkVolume:
          type: integer
        name:
          type: string
      required:
        - species
        - name

In this example, the /pet endpoint demonstrates a multiple response scenario:

• 200 status with a oneOf schema that can return either:
  • Cat - an object with species, whiskerLength, and name properties
  • Dog - an object with species, barkVolume, and name properties

liblab will generate a method that returns a named response model containing a OneOf type that can represent either a Cat or a Dog. The generated SDK provides a switchPet method that allows you to handle each variant safely. Error responses (4xx and 5xx) are typically handled separately through exception handling mechanisms in the generated SDKs.

Language-Specific Implementations

liblab generates consistent implementations across all supported languages. When your OpenAPI specification defines multiple responses with different schemas or content types, the generated SDK methods return a unified type that represents all possible response models.

For strongly typed languages (Java, C#, Go), liblab generates a named wrapper model that internally uses a OneOf utility to represent all possible response variants. This preserves compile-time type safety and allows developers to handle each variant through language-specific pattern matching or type-switch mechanisms.

For languages with structural or dynamic typing (TypeScript, Python, PHP), liblab generates a union-like type or wrapper class that enables developers to check the response variant at runtime and access the corresponding model.

Regardless of the target language, the generated SDKs provide a consistent but idiomatic developer experience for handling multiple response types, ensuring type safety where supported and clear runtime type checking where applicable.

Usage Examples

The following examples demonstrate how to use the generated SDK method for the /pet endpoint with multiple response types. Each example shows how to:

1. Call the API method that returns a response model with a OneOf type
2. Handle different response types using the generated switchPet method
3. Access response data based on the actual response type received (Cat or Dog)

The OneOf type allows you to safely handle all possible response variants that the API might return, ensuring your code is robust and type-safe.

Go

resp, err := sdk.Pets.GetPet(context.Background())

resp.Data.SwitchPet(
    resp.Data,
    func(cat testsdkmodels.Cat) {
        fmt.Printf("Cat: %+v\n", cat)
    },
    func(dog testsdkmodels.Dog) {
        fmt.Printf("Dog: %+v\n", dog)
    },
)

TypeScript

const resp = await sdk.pets.getPet();

const pet = resp.data;
if (isDog(pet)) {
    console.log('Dog: ', pet);
} else if (isCat(pet)) {
    console.log('Cat: ', pet);
}

Python

resp = await sdk.pets.get_pet()

pet = resp.data
if isinstance(pet, Dog):
    print("Dog:", pet)
elif isinstance(pet, Cat):
    print("Cat:", pet)