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: The easiest and most flexible approach
2. 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