Customize Imports

Speakeasy allows you to customize the paths we generate models to and your users import models from.

By default, Speakeasy uses an OpenAPI-based naming scheme for the namespaces models are bucketed into, for example:

INFO

Currently only supported for C#, Go, Python, TypeScript, and Unity SDKs. More languages will be added soon.

Models generated from components are placed in the models/components directory, or the target language idiomatic equivalent.

Models generated from operations are placed in the models/operations directory, or the target language idiomatic equivalent.

Models that are used in error status codes are placed in the models/errors directory, or the target language idiomatic equivalent.

gen.yaml

sdk/
├─ models/
│  ├─ components/
│  │  ├─ user.ts
│  │  ├─ drink.ts
│  │  └─ ...
│  ├─ operations/
│  │  ├─ getuser.ts
│  │  ├─ updateuser.ts
│  │  ├─ getdrink.ts
│  │  ├─ updatedrink.ts
│  │  └─ ...
│  └─ errors/
│     ├─ sdkerror.ts
│     ├─ responseerror.ts
│     └─ ...
└─ ...

WARN

The default names for the model directories are consistent across most targets, but C# makes the exception that the models/Operations directory is called models/Requests by default.

Customize Import Paths

Customize where path models are generated to and imported from by modifying the configuration in the gen.yaml file.

Configuration like what is shown will result in a file structure as above.

The option key determines the type of bucketing scheme that is used for the models.

Only openapi is currently supported. This will bucket models into components, operations, errors, callbacks, and webhooks directories.

The paths section contains a map of bucket names to paths relative to the root of the generated SDK.

shared refers to the models generated from the components section of the OpenAPI specification. (Note: shared is a legacy name for the bucket, retained for backward compatibility.)
operations refers to the models generated for the request and responses of operations in the OpenAPI specification.
errors refers to the models generated for schemas referenced in error status codes responses.
callbacks refers to models generated for schemas within the callbacks section of an operation.
webhooks refers to models generated from the webhooks section of an OpenAPI 3.1 document.

gen.yaml

configVersion: 2.0.0
generation:
  # ...
typescript:
  version: 1.0.0
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
  # ...

You can customize these paths to any path that exists relative to the root of the SDK.

CAUTION

If you are providing custom path names, make sure there is no conflict with any of the existing directories in the SDK. Conflicts will result in compilation issues.

Different buckets can also be configured to use the same path, for example:

gen.yaml

typescript:
  ...
  imports:
    option: openapi
    paths:
      callbacks: models
      errors: models
      operations: models
      shared: models
      webhooks: models

This will result in all models being generated to the models directory. The generator will then resolve any class name conflicts by prefixing or suffixing class names to ensure they are unique.

Customize Global Imports

You can configure the generator to work with a global import path for all models.

For example:

import { User, GetDrinkRequest, SDK } from '@speakeasy/bar'

Instead of:

import { SDK } from '@speakeasy/bar'
import { User } from '@speakeasy/bar/dist/models/components/user'
import { GetDrinkRequest } from '@speakeasy/bar/dist/models/operations/user'

You will configure global imports slightly differently for different languages:

For TypeScript to configure global imports, the imports section of your gen.yaml needs to include the following:

gen.yaml

typescript:
  ...
  imports:
    option: openapi
    paths:
      callbacks: models
      errors: models
      operations: models
      shared: models
      webhooks: models

# OR

typescript:
  ...
  imports:
    option: openapi
    paths:
      callbacks: ""
      errors: ""
      operations: ""
      shared: ""
      webhooks: ""

For global imports in TypeScript, models will always be generated to the models directory, regardless of whether the "" or "models" path is specified. However, global imports will only kick in if one of these two values is used for all buckets. This is to ensure the root directory isn’t cluttered with files.

The configuration example above will result in a directory structure like this:

/
├─ src
│  ├─ models/
│  │  ├─ user.ts
│  │  ├─ drink.ts
│  │  ├─ getuser.ts
│  │  ├─ updateuser.ts
│  │  ├─ getdrink.ts
│  │  ├─ updatedrink.ts
│  │  ├─ sdkerror.ts
│  │  ├─ responseerror.ts
│  │  ├─ index.ts
│  │  └─ ...
│  └─ ...
└─ ...

Import models like so:

import { User, GetDrinkRequest, SDK } from '@speakeasy/bar'

For Python to configure global imports, the imports section of your gen.yaml needs to include the following:

gen.yaml

python:
  ...
  imports:
    option: openapi
    paths:
      callbacks: models
      errors: models
      operations: models
      shared: models
      webhooks: models

# OR

python:
  ...
  imports:
    option: openapi
    paths:
      callbacks: ""
      errors: ""
      operations: ""
      shared: ""
      webhooks: ""

For global imports in Python, models will always be generated to the models directory, regardless of whether the "" or "models" path is specified. However, global imports will only kick in if one of these two values is used for all buckets. This is to ensure the root directory isn’t cluttered with files.

The configuration example above will result in a directory structure as follows:

/
├─ src
│  ├─ sdk/
│  │  ├─ models/
│  │  |  ├─ user.py
│  │  │  ├─ drink.py
│  │  │  ├─ getuser.py
│  │  │  ├─ updateuser.py
│  │  │  ├─ getdrink.py
│  │  │  ├─ updatedrink.py
│  │  │  ├─ sdkerror.py
│  │  │  ├─ responseerror.py
│  │  │  └─ __init__.py
│  │  └─ ...
│  └─ ...
└─ ...

Import like so:

import speakeasybar

Instead of:

import speakeasybar
from speakeasybar.models import operations, components

For Go to configure global imports, the imports section of your gen.yaml needs to include the following:

gen.yaml

go:
  ...
  imports:
    option: openapi
    paths:
      callbacks: ""
      errors: ""
      operations: ""
      shared: ""
      webhooks: ""

This configuration will instruct the generator to create models at the root of the SDK and result in the following directory structure:

/
├─ user.go
├─ drink.go
├─ getuser.go
├─ updateuser.go
├─ getdrink.go
├─ updatedrink.go
├─ sdkerror.go
├─ responseerror.go
└─ ...

Note: This configuration will result in the root directory being cluttered with files.

Import models like so:

import (
  "github.com/speakeasy/bar"
)

Instead of:

import (
  "github.com/speakeasy/bar"
  "github.com/speakeasy/bar/models/operations"
  "github.com/speakeasy/bar/models/components"
)

For C# to configure global imports, the imports section of your gen.yaml needs to include the following:

gen.yaml

csharp:
  ...
  imports:
    option: openapi
    paths:
      callbacks: Models
      errors: Models
      operations: Models
      shared: Models
      webhooks: Models

# OR

csharp:
  ...
  imports:
    option: openapi
    paths:
      callbacks: ""
      errors: ""
      operations: ""
      shared: ""
      webhooks: ""

For global imports in C#, models will always be generated to the Models directory, regardless of whether the "" or "Models" path is specified. However, global imports will only kick in if one of these two values is used for all buckets. This is to ensure the root directory isn’t cluttered with files.

The above configuration will result in a directory structure like this:

/
├─ {{packageName}}/
│  ├─ Models/
│  │  ├─ User.cs
│  │  ├─ Drink.cs
│  │  ├─ GetUserRequest.cs
│  │  ├─ GetUserResponse.cs
│  │  ├─ UpdateUserRequest.cs
│  │  ├─ UpdateUserResponse.cs
│  │  ├─ GetDrinkRequest.cs
│  │  ├─ GetDrinkResponse.cs
│  │  ├─ UpdateDrinkRequest.cs
│  │  ├─ UpdateDrinkResponse.cs
│  │  ├─ SDKError.cs
│  │  ├─ ResponseError.cs
│  │  └─ ...
│  └─ ...
└─ ...

As all the models will be under the root namespace of the SDK, import models like so:

using SpeakeasyBar;

For Unity to configure global imports, the imports section of your gen.yaml needs to include the following:

gen.yaml

unity:
  ...
  imports:
    option: openapi
    paths:
      callbacks: Models
      errors: Models
      operations: Models
      shared: Models
      webhooks: Models

# OR

unity:
  ...
  imports:
    option: openapi
    paths:
      callbacks: ""
      errors: ""
      operations: ""
      shared: ""
      webhooks: ""

For global imports in Unity, models will always be generated to the Models directory, regardless of whether the "" or "Models" path is specified. However, global imports will only kick in if one of these two values is used for all buckets. This is to ensure the root directory isn’t cluttered with files.

The configuration example above will result in a directory structure like this:

/
├─ {{packageName}}/
│  ├─ Models/
│  │  ├─ User.cs
│  │  ├─ Drink.cs
│  │  ├─ GetUserRequest.cs
│  │  ├─ GetUserResponse.cs
│  │  ├─ UpdateUserRequest.cs
│  │  ├─ UpdateUserResponse.cs
│  │  ├─ GetDrinkRequest.cs
��  │  ├─ GetDrinkResponse.cs
│  │  ├─ UpdateDrinkRequest.cs
│  │  ├─ UpdateDrinkResponse.cs
│  │  ├─ SDKError.cs
│  │  ├─ ResponseError.cs
│  │  └─ ...
│  └─ ...
└─ ...

As all the models will be under the root namespace of the SDK, import models like so:

using SpeakeasyBar;

CAUTION

Global imports will cause namespace pollution for the import and file clutter in the directory models are generated to.

Large APIs containing many models (especially many inline models) will inevitably lead to name conflicts. Rename types verbosely to ensure each class is unique within the namespace.