Speakeasy Workflow File

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


workflowVersion: 1.0.0
speakeasyVersion: v1.250.0
...

Sources

Sources can be added to a workflow programmatically speakeasy configure sources or manually by editing the workflow file.

`sources`

Sources are the inputs to the workflow. A single Source is one or more OpenAPI documents and Overlays that are merged together to create a single OpenAPI document.


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:
  python-sdk:
    target: python
    source: my-source
  # more inputs can be added here through `speakeasy configure targets` command
  # ....
  # ....

`my-source`

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


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:
  python-sdk:
    target: python
    source: my-source
  # more inputs can be added here through `speakeasy configure targets` command
  # ....
  # ....

`inputs`

Each Source has a list of inputs. Each input is an OpenAPI document or Overlay. The OpenAPI documents and Overlays are merged together to create a single OpenAPI document.


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:
  python-sdk:
    target: python
    source: my-source
  # more inputs can be added here through `speakeasy configure targets` command
  # ....
  # ....

`location`

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 a URL is a used authentication may need to be provided.


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:
  python-sdk:
    target: python
    source: my-source
  # more inputs can be added here through `speakeasy configure targets` command
  # ....
  # ....

`sources`

Sources are the inputs to the workflow. A single Source is one or more OpenAPI documents and Overlays that are merged together to create a single OpenAPI document.

`my-source`

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

`inputs`

Each Source has a list of inputs. Each input is an OpenAPI document or Overlay. The OpenAPI documents and Overlays are merged together to create a single OpenAPI document.

`location`

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 a URL is a used authentication may need to be provided.


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:
  python-sdk:
    target: python
    source: my-source
  # more inputs can be added here through `speakeasy configure targets` command
  # ....
  # ....

Targets

Targets can be added to a workflow programmatically speakeasy configure targets or manually by editing the workflow file.

`targets`

Targets are the outputs of the workflow. A single Target is a SDK, Terraform or other generated artifact from sources.


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

`my-target`

Each Target is given a name. In this example the name is my-target. This name is used to reference the target in the workflow file.


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`

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


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

`source`

Each Target has a source. The source is the name of the source that the target will be generated from.


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