Core Concepts
The core concepts explained on this page are essential to understanding the Speakeasy platform. To skip to getting started with the platform, go here.
Workflows
A workflow is how the Speakeasy platform defines the process of generating a target from a source. A workflow is defined in a workflow.yaml
file stored in the root of the target repository in the .speakeasy
directory. A workflow is run using the speakeasy run
command.
Workflow File Syntax
The workflow.yaml
workflow file is a YAML file that defines the steps of a workflow. The file is broken down into the following sections:
workflowVersion: 1.0.0speakeasyVersion: latestsources: my-source: inputs: - location: ./openapi.yaml - location: ./overlay.yaml - location: ./another-openapi.yaml - location: ./another-overlay.yaml # .... more openapi documents and 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 # .... # ....
The workflow file syntax allows for 1:1, 1:N, or N:N mapping of sources
to targets
. A common use case for 1:N mapping is setting up a monorepo of SDKs. See our monorepo guide for details.
Sources
A source is one or more OpenAPI documents and overlays merged to create a single OpenAPI document. Sources are defined in the workflow.yaml
file.
Targets
A target is an SDK, Terraform provider, or other code generated from sources. Sources are defined in the workflow.yaml
file.
SDK Generation
The following concepts are specific to the SDK generation type of target. Please see our template-sdk
(opens in a new tab) for examples of the concepts.
The Generation Config File
The Speakeasy CLI uses the gen.yaml
generation config file to generate a target. The gen.yaml
file is stored in the root of a target repository in the .speakeasy
directory. For a full reference of the gen.yaml
file, see the reference doc.
The Generation State File
The Speakeasy CLI uses the gen.lock
generation state file to track the state of a generation. The gen.lock
file includes a generation UUID, management
and feature
versions, and the list of generated files managed through the Speakeasy CLI. The file is stored in the root of a target repository in the .speakeasy
directory.
Releases and Versioning
Speakeasy automatically creates releases and versions for your target artifacts. The release and version are defined in the gen.yaml
file and used to track the state of a generation and create a release on the target repository. Releases (opens in a new tab) are used synonymously with GitHub Releases, the primary way Speakeasy distributes artifacts. For more information on how to manage versioning, see our versioning reference.
GitHub Workflow
The GitHub Workflow is a set of GitHub actions used to automate the generation of a target. The GitHub Workflow is defined in the .github/workflows
directory of a target repository. For a complete reference of the GitHub Workflow, see the documentation. These files can be set up using the speakeasy configure github
CLI command.
OpenAPI Specification (OAS)
The OpenAPI Specification (OAS) is a widely accepted REST specification for building APIs. An OpenAPI document is a JSON or YAML file that defines the structure of an API. The Speakeasy platform uses OpenAPI documents as the source for generating SDKs and other code.
Overlay
An overlay is a JSON or YAML file used to add, remove, or modify parts of an OpenAPI document and customize the generated code. Overlays used to alter an OpenAPI document are defined in the workflow.yaml
file.
Linting
Linting is the process of checking an OpenAPI document for errors and style issues. The Speakeasy platform defines linting rules used to validate an OpenAPI document. Linting is done using the speakeasy lint
command, and linting rules are defined in the lint.yaml
file.
Validation
Validation is the process of checking if an OpenAPI document is ready for code generation. The Speakeasy platform defines validation rules used to validate an OpenAPI document. Validation is done using the speakeasy validate
command, and validation rules are defined in the lint.yaml
file.
By default the validate
CLI command will use the speakeasy-default
linting ruleset if custom rules are not defined.