oneOf Schemas

In support of the OpenAPI Specification of oneOf schemas, Speakeasy SDKs provide language specific implementations based around idiomatic Unions when available, or otherwise using generated supporting objects that allow type safety by using an enum discriminator.

Supporting Objects

Assuming that your spec has a Pet component, for this oneOf block:


oneOf:
  - type: string
  - type: integer
  - $ref: "/components/schemas/Pet"

Speakeasy would generate the following supporting objects for your SDK:

Because go does not provide a native union data type, Speakeasy will create a supporting struct, with a corresponding psuedo enum that is used for discrimination. The naming of the supporting object will depend on whether it is being used as part of a request, or is being included as a response.

The generated object can optionally accept any of the oneOf types, but should only store one at a time, and the Type field should store the corresponding const value:


type FetchPetRequestBodyType string
const (
	FetchPetRequestBodyTypeStr          FetchPetRequestBodyType = "str"
	FetchPetRequestBodyTypeInteger      FetchPetRequestBodyType = "integer"
	FetchPetRequestBodyTypePet          FetchPetRequestBodyType = "pet"
)
type FetchPetRequestBody struct {
	Str          *string
	Integer      *int64
	Pet *shared.Pet
	Type FetchPetRequestBodyType
}

As a user of the SDK, you shouldn't construct a FetchPetRequestBody object yourself, but instead call one of the supporting Create methods that set the content value and discriminator for you.


func CreateFetchPetRequestBodyStr(str string) FetchPetRequestBody {
	typ := FetchPetRequestBodyTypeStr
	return FetchPetRequestBody{
		Str:  &str,
		Type: typ,
	}
}
func CreateFetchPetRequestBodyInteger(integer int64) FetchPetRequestBody {
	typ := FetchPetRequestBodyTypeInteger
	return FetchPetRequestBody{
		Integer: &integer,
		Type: typ,
	}
}
func CreateFetchPetRequestBodyPet(pet shared.Pet) FetchPetRequestBody {
	typ := FetchPetRequestBodyTypePet
	return FetchPetRequestBody{
		Pet: &pet,
		Type: typ,
	}
}

Requests

Assuming that you have an operation that allowed the user to fetch a pet either by submiting the pet's name, the pet's id, or a complete pet object:


/pet:
  get:
    operationId: fetchPet
    parameters:
      - name: pet
        schema:
          oneOf:
            - type: string
            - type: integer
            - $ref: "/components/schemas/Pet"

You can then use the returned object from the supporting Create functions as the request parameter on the operation's request:


s := sdk.New()
req := shared.CreateFetchPetRequestBodyInteger(1)
res, err := s.Pets.FetchPet(context.Background(), req)

Responses

Sometimes you may have a response that specifies a oneOf schema. As above, with requests, in languages that do not natively support Unions, Speakeasy will create supporting objects to deserialize the oneOf response into the correct object type. In languages where a native Union type exists, no supported objects are needed, and deserialization into the native type will occur.

For example, this schema:


/pet_id:
  get:
    operationId: petId
    responses:
      "200":
        description: OK
        content:
          application/json:
            schema:
              title: res
              oneOf:
                - type: string
                - type: integer

Will result in these response types:


type petIdResType string
const (
	PetIdResTypeStr          petIdResType = "str"
	PetIdResTypeInteger      petIdResType = "integer"
)
type petIdRes struct {
	Str          *string
	Integer      *int64
	Type petIdResType
}
type FetchPetResponse struct {
	// ..snip
	Res *petIdRes
}