Transformations

Transformations are predefined functions that can be applied to an OpenAPI document to change its structure.

Speakeasy currently supports the following transformations:

  • Remove unused components: Removes components that are not referenced by any operation.
  • Filter operations: Filters operations down to a user-defined set of operation IDs.
  • Cleanup: Reformats the document to be more readable and compliant with various parsing tools.
  • Format: Changes the order of keys at various levels in the document to be more human-readable.
  • Convert Swagger to OpenAPI: Converts a Swagger 2.0 document to an OpenAPI 3.0.x document.

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, overlays are static and do not evolve with the underlying document. Taking the example of removing an unused component, an overlay 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 and most flexible way to apply transformations to an OpenAPI document.
  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
  • speakeasy openapi transform format -s openapi.yaml
  • speakeasy openapi transform convert-swagger -s swagger.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.

The convert-swagger transformation is an exception, as it cannot be applied as part of a workflow.

Remove unused components

Remove unused components from the OpenAPI document, preventing them from being included in the generated SDK.


Filter operations

Keep or remove the specified operations from the OpenAPI document.


Cleanup

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


Format

Changes the order of keys at various levels in the document, formatting it to be more human-readable.


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
- format: true