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:

Using the CLI: The easiest and most flexible approach
As part of a Speakeasy workflow: 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.


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.


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.


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.


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:


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.


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:


speakeasy openapi snip -s openapi.yaml

Last updated on January 22, 2026