# Transformations

Transformations are predefined functions that modify an OpenAPI document's structure.

Speakeasy currently supports the following transformations:

- **Remove unused components:** Removes components not referenced by any operation
- **Filter operations:** Filters operations down to a defined set of operation IDs
- **Cleanup:** Reformats the document for better readability and compliance with various parsing tools
- **Format:** Changes the order of keys at various levels in the document for improved human readability
- **Convert Swagger to OpenAPI:** Converts a Swagger 2.0 document to an OpenAPI 3.0.x document (automatically applied in workflows when a Swagger 2.0 document is detected)
- **Normalize:** Normalizes the document structure (for example, converting `prefixItems` to simple string types)
- **Snip:** Removes or keeps specific operations by operation ID or path and method

## Transformations vs. overlays

Transformations and overlays both modify OpenAPI documents but differ in key ways:

- **Transformations** operate dynamically and account for changes to the underlying document, staying "always up to date." For example,
if an OpenAPI document updates and a previously unused component becomes used by a newly-added operation, the `removeUnused` transformation will no longer remove it.
- **Overlays** offer more flexibility and can transform almost any document into any other document. However, overlays remain static and do not adapt with the underlying document.
For example, when removing an unused component, an overlay continues to remove it even if the underlying document changes and the component becomes used.

## Using transformations

Apply transformations to an OpenAPI document in two ways:

1. [Using the CLI](#using-the-cli): The easiest and most flexible approach
2. [As part of a Speakeasy workflow](#in-workflow-files): The most powerful approach, requiring more initial setup

### Using the CLI

Apply a transformation to an OpenAPI document with the `speakeasy openapi transform` command. The interactive CLI guides through the process. Example commands:

- `speakeasy openapi transform remove-unused -s openapi.yaml`
- `speakeasy openapi transform filter-operations -s openapi.yaml --operations=getPets,createPet`
- `speakeasy openapi transform cleanup -s openapi.yaml`
- `speakeasy openapi transform format -s openapi.yaml`
- `speakeasy openapi transform convert-swagger -s swagger.yaml`
- `speakeasy openapi transform normalize -s openapi.yaml`
- `speakeasy openapi snip -s openapi.yaml`

### In workflow files

The greatest utility comes from using transformations in the `workflow.yaml` file. This keeps the OpenAPI document always up to date with desired transformations, though it requires more initial setup.

Swagger 2.0 documents are automatically detected and converted to OpenAPI 3.x during workflow execution. This conversion runs after overlay operations but before other transformations. There is no need to add a `convert-swagger` step to a workflow — it happens implicitly whenever a Swagger 2.0 source document is detected.

### Remove unused components

Remove unused components from the OpenAPI document, preventing inclusion in the generated SDK.

```yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml
    transformations:
      - removeUnused: true
      - filterOperations:
          operations: getPets, createPet
          include: true
      - cleanup: true
      - format: true
```

### Filter operations

Keep or remove specified operations from the OpenAPI document.

```yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml
    transformations:
      - removeUnused: true
      - filterOperations:
          operations: getPets, createPet
          include: true # exclude: true
      - cleanup: true
      - format: true
```

### Cleanup

Clean up the OpenAPI document for improved readability and compliance with various parsing tools.

```yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml
    transformations:
      - removeUnused: true
      - filterOperations:
          operations: getPets, createPet
          include: true
      - cleanup: true
      - format: true
```

### Format

Reorder keys at various document levels for enhanced human readability.

```yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml
    transformations:
      - removeUnused: true
      - filterOperations:
          operations: getPets, createPet
          include: true
      - cleanup: true
      - format: true
```

### Convert Swagger to OpenAPI

Convert a Swagger 2.0 document to an OpenAPI 3.x document. In workflows, this conversion is applied automatically when a Swagger 2.0 source document is detected — no manual configuration is needed. To convert explicitly using the CLI:

```bash
speakeasy openapi transform convert-swagger --schema swagger.yaml --out openapi.yaml
```

### Normalize

Normalize the structure of the OpenAPI document. This transformation simplifies certain patterns in the document, such as converting `prefixItems` to simple string types.

```yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  api-source:
    inputs:
      - location: ./openapi.yaml
    transformations:
      - normalize: true
```

### Snip

Remove or keep specific operations by operation ID or path and method. This is available as a standalone CLI command:

```bash
speakeasy openapi snip -s openapi.yaml
```