Transformations

Transformations are pre-defined functions that can be applied to an OpenAPI document to improve its quality. Speakeasy currently supports the following:

  • Remove unused components: Removes components that are not referenced by any operation.
  • Filter operations: Filters operations down to a user-defined set of operationIDs.
  • Cleanup: Reformats the document to be more readable and compliant with various parsing tools.

Transformations vs. Overlays

Transformations and overlays are similar in that they both allow you to modify an OpenAPI document. However, there are some key differences between the two:

  • Transformations are dynamic and will account for any changes to the underlying document. In this way, they are “always up to date”. For example, if your OpenAPI document updates and a previously unused component becomes used by a newly-added operation, the removeUnused transformation will no longer remove it.
  • Overlays are more flexible and can change almost any document into any other document. However—unlike Transformations—they are static and do not evolve with the underlying document. Taking the example of removing an unused component, the overlay version will continue to remove it even if the underlying document changes and the component becomes used.

Using Transformations

Speakeasy provides two ways to apply transformations to an OpenAPI document.

  1. Using the CLI. This is the easiest way to apply a transformation to an OpenAPI document. It’s also the most flexible way to apply transformations.
  2. As part of your Speakeasy workflow. This is the most powerful way to apply transformations, but requires a bit more setup.

Using the CLI

To apply a transformation to an OpenAPI document, use the speakeasy openapi transform command. The interactive CLI will walk you through the rest. Here are a few 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

In Workflow Files

The real utility of transformations comes when you use them in your workflow.yaml file. This allows your OpenAPI document to be always up-to-date with the desired transformations, but requires a bit more setup.

Remove Unused Components

Remove unused components from the OpenAPI document, thus preventing them from ending up in the generated SDK.


Filter Operations

Keep or remove the specified operations from the OpenAPI document.


Cleanup

Cleanup the OpenAPI document, making it more readable and compliant with various parsing tools.

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