Speakeasy Workflow File

Info Icon

TIP

For most use cases we recommend interacting with the Speakeasy workflow file (workflow.yaml) through the speakeasy configure command. This command has subcommands to configure your sources, targets, github setup and package publishing. All new targets created through speakeasy quickstart will automatically have a workflow file created in the .speakeasy/ folder in the root of their target directory.

For editing the workflow file manually, VS Code Speakeasy’s VSCode extension (opens in a new tab) provides syntax highlighting and autocompletion for the workflow file, in addition to linting for OpenAPI documents, and our other supported file types.

The workflow file is a file that dictates how the Speakeasy CLI will interact with sources and targets. The interaction is modelled as a workflow between sources and targets. A Source is one or more OpenAPI documents and Overlays merged together to create a single OpenAPI documents. A Target is a SDK, Terraform or other generated artifact from sources.

File Structure

Speakeasy Version

The version of the Speakeasy CLI to use to run the workflow. The version can be a specific version or latest to use the latest version. Pinning to a specific version can be useful to ensure that the workflow runs consistently across different environments.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: v1.250.0

Sources

sources is a collection of inputs to a workflow. A source is composed of one or more OpenAPI documents and optionally, overlays, that get merged together to create a single OpenAPI document. Sources can be added to a workflow programmatically speakeasy configure sources or manually by editing the workflow file.

Each Source is given a name. In the example below, my-source is used to reference the source in the workflow file.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

      - location: ./another-openapi.yaml

      # .... more openapi documents can be added here

    overlays:

      - location: ./overlay.yaml

      - location: ./another-overlay.yaml

      # .... more openapi overlays can be added here

  # .... more inputs can be added here through `speakeasy configure sources` command

    transformations:

      # Remove unused components from the OpenAPI document

      - removeUnused: true

      # Filter to include only specific operations

      - filterOperations:

          operations: getPets, createPet

          include: true

      # General cleanup of the OpenAPI document (formatting and style)

      - cleanup: true

targets:

  python-sdk:

    target: python

    source: my-source

  # .... more inputs can be added here through `speakeasy configure targets` command

inputs

Each input has a location. The location is the path to the OpenAPI document or Overlay. The path can be a local reference or a remote URL. If the URL is private, authentication is required.

transformations

Sources can include transformations that modify the OpenAPI document before it’s used to generate SDKs. Transformations are applied in order after merging inputs and applying overlays.

The available transformations are:

  • removeUnused - Removes components not referenced by any operation
  • filterOperations - 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
  • convertSwagger - Converts a Swagger 2.0 document to an OpenAPI 3.0.x document
workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

      - location: ./another-openapi.yaml

      # .... more openapi documents can be added here

    transformations:

      # Remove unused components from the OpenAPI document

      - removeUnused: true

      # Filter to include only specific operations

      - filterOperations:

          operations: getPets, createPet

          include: true

      # General cleanup of the OpenAPI document (formatting and style)

      - cleanup: true

targets:

  python-sdk:

    target: python

    source: my-source

  # .... more inputs can be added here through `speakeasy configure targets` command

output

Each source can specify an output location where the merged OpenAPI document will be written.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

    output: ./merged-openapi.yaml

registry

Sources can be configured to publish to the API Registry found in your Speakeasy workspace.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

    registry:

      location: registry.speakeasyapi.dev/my-org/my-api

Targets

Targets are the outputs of the workflow. A single Target is a SDK, Terraform or other generated artifact from sources. Targets can be added to a workflow programmatically speakeasy configure targets or manually by editing the workflow file.

Each Target must have a name, a target and a source. In this example the name is my-target. This name is used to reference the target in the workflow file.

There are additional optional information that can be added to a target to take advantage of additional platform features.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

      - location: ./another-openapi.yaml

      # .... more openapi documents can be added here

    overlays:

      - location: ./overlay.yaml

      - location: ./another-overlay.yaml

      # .... more openapi overlays can be added here

  # more inputs can be added here through `speakeasy configure sources` command

  # ....

  # ....

targets:

  my-target:

    target: python

    source: my-source

  # more inputs can be added here through `speakeasy configure targets` command

  # ....

  # ....

target

The target is the type of artifact that will be generated from the sources. The target can be one of the supported languages here

source

Each Target has a source. The source is the name of the source in the workflow file that the target should be generated from.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

      - location: ./another-openapi.yaml

      # .... more openapi documents can be added here

    overlays:

      - location: ./overlay.yaml

      - location: ./another-overlay.yaml

      # .... more openapi overlays can be added here

  # more inputs can be added here through `speakeasy configure sources` command

  # ....

  # ....

targets:

  my-target:

    target: python

    source: my-source

  # more inputs can be added here through `speakeasy configure targets` command

  # ....

  # ....

testing

Each Target supports enabling testing as part of the workflow, if test generation is licensed. This will run target-specific testing, such as go test or pytest, after code generation. Use this with CLI-only speakeasy run development workflows (instead of separately calling speakeasy test) or GitHub Actions mode: direct or mode: test development workflows to ensure tests are successful with any potential code updates.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

      - location: ./another-openapi.yaml

      # .... more openapi documents can be added here

    overlays:

      - location: ./overlay.yaml

      - location: ./another-overlay.yaml

      # .... more openapi overlays can be added here

  # more inputs can be added here through `speakeasy configure sources` command

  # ....

  # ....

targets:

  my-target:

    target: python

    source: my-source

    testing:

      enabled: true

  # more inputs can be added here through `speakeasy configure targets` command

  # ....

  # ....

mockServer

Target testing, when licensed and enabled, starts a mock API server automatically as part of the workflow. This disables the mock API server, if the testing should always pointed at a test environment server URL instead.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

      - location: ./another-openapi.yaml

      # .... more openapi documents can be added here

    overlays:

      - location: ./overlay.yaml

      - location: ./another-overlay.yaml

      # .... more openapi overlays can be added here

  # more inputs can be added here through `speakeasy configure sources` command

  # ....

  # ....

targets:

  my-target:

    target: python

    source: my-source

    testing:

      enabled: true

      mockServer:

        enabled: false

  # more inputs can be added here through `speakeasy configure targets` command

  # ....

  # ....

codeSamples

Each target can be configured to generate code samples and publish them to Speakeasy’s registry.

workflow.yaml
workflowVersion: 1.0.0

speakeasyVersion: latest

sources:

  my-source:

    inputs:

      - location: ./openapi.yaml

targets:

  my-target:

    target: python

    source: my-source

    codeSamples:

      output: codeSamples.yaml

      registry:

        location: registry.speakeasyapi.dev/my-org/my-api/code-samples