# Customize imports
Source: https://speakeasy.com/docs/sdks/customize/structure/imports

import { Callout, CodeWithTabs } from "@/mdx/components";



Speakeasy allows customization of the paths for generated models and model imports.

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

<Callout title="Info" type="info">
Currently only supported for C#, Go, Python, TypeScript, and Unity SDKs. More languages will be added soon.
</Callout>

### Components

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

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

### Operations

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

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

### Errors

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

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

<Callout title="Warning" type="warning">
  The default names for the model directories are consistent across most target
  languages, but C# makes the exception that the `models/Operations` directory
  is called `models/Requests` by default.
</Callout>

## Customize import paths

### imports

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.

```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
  # ...
```

### option

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.

```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
  # ...
```

### paths

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.

```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.

<Callout title="Caution" type="warning">
  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.
</Callout>

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

```yaml filename="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:

```typescript
import { User, GetDrinkRequest, SDK } from "@speakeasy/bar";
```

Instead of:

```typescript
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:

<br></br>

<CodeWithTabs
  tabs={[
    {
      label: "TypeScript",
      language: "yaml",
      code: `# For TypeScript to configure global imports, the \`imports\` 
  # section of your \`gen.yaml\` needs to include the following:

  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'`,

    },
    {
      label: "Python",
      language: "yaml",
      code: `# For Python to configure global imports, the \`imports\` section
  # of your \`gen.yaml\` needs to include the following:

  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`,

    },
    {
      label: "Go",
      language: "yaml",
        code: `# For Go to configure global imports, the \`imports\` section
  # of your \`gen.yaml\` needs to include the following:

  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"
  # )`,

    },
    {
      label: "C#",
      language: "yaml",
      code: `# For C# to configure global imports, the \`imports\` section
  # of your \`gen.yaml\` needs to include the following:

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