Transformations

Transformations are pre-defined functions that can be applied to an OpenAPI document to change its structure. 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.
• 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 specification.

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
• 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.

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

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