Speakeasy Workflow File

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.

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
    transformations:

SourceName

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.

  my-source:

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.

    inputs:
      - location: ./openapi.yaml
      - location: ./another-openapi.yaml
      # .... more openapi documents can be added here

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.

      - location: ./openapi.yaml
      - location: ./another-openapi.yaml
      # .... more openapi documents can be added here

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.

      # .... more openapi overlays 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)

Output

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

    output: ./merged-openapi.yaml

Registry

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

    registry:
      location: registry.speakeasy.com/my-org/my-api

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.

targets:
  my-target:
    target: python
    source: my-source
    testing:
      enabled: true
      mockServer:
        enabled: false

TargetName

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.

  my-target:

TargetType

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

    target: python

TargetSource

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

    source: my-source

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.

    testing:
      enabled: true
      mockServer:
        enabled: false

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.

      mockServer:
        enabled: false

CodeSamples

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

    codeSamples:
      output: codeSamples.yaml
      registry:
        location: registry.speakeasy.com/my-org/my-api/code-samples