SDK Sandboxes

Speakeasy can generate dev container configurations for SDK repositories to provide an intuitive, predefined sandbox environment for exploring SDK capabilities. Beyond setting up this environment, Speakeasy has CLI commands that allow SDK users to effortlessly generate example usage snippets for any API operation within this container setting.

TIP

SDK Sandboxes are currently available in Go, TypeScript, and Python SDKs.

Configuring SDK Sandboxes

To set up the automatically generated dev container configurations, minor adjustments to the gen.yaml file are required. The schemaPath shown below should reference the SDK’s OpenAPI document, which can be a local path or a remote URL.

Dev container gen.yaml:

configVersion: 1.0.0
generation:
  devContainers:
    enabled: true
    schemaPath: ./openapi.yaml

Generation will create a .devcontainer directory containing a configuration file similar to below.

Generated devcontainer.json:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/go
{
    "name": "Go",
    "image": "mcr.microsoft.com/devcontainers/go:1-1.20-bullseye",
    // Features to add to the dev container. More info: https://containers.dev/features.
    // "features": {},
    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],
    // Use 'postCreateCommand' to run commands after the container is created.
    "postCreateCommand": "sudo chmod +x ./.devcontainer/setup.sh && ./.devcontainer/setup.sh",
    "customizations": {
        "vscode": {
            "extensions": [
                "golang.go",
                "github.vscode-pull-request-github" // Github interaction
            ],
            "settings": {
                "files.eol": "\n",
                "editor.formatOnSave": true,
                "go.buildTags": "",
                "go.toolsEnvVars": {
                    "CGO_ENABLED": "0"
                },
                "go.useLanguageServer": true,
                "go.testEnvVars": {
                    "CGO_ENABLED": "1"
                },
                "go.testFlags": [
                    "-v",
                    "-race"
                ],
                "go.testTimeout": "60s",
                "go.coverOnSingleTest": true,
                "go.coverOnSingleTestFile": true,
                "go.coverOnTestPackage": true,
                "go.lintTool": "golangci-lint",
                "go.lintOnSave": "package",
                "[go]": {
                    "editor.codeActionsOnSave": {
                        "source.organizeImports": true
                    }
                },
                "gopls": {
                    "usePlaceholders": false,
                    "staticcheck": true,
                    "vulncheck": "Imports"
                }
            }
        },
        "codespaces": {
            "openFiles": [
                ".devcontainer/README.md"
            ]
        }
    }
    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
    // "remoteUser": "root"
}

Using SDK Sandboxes in the browser

SDK users can instantly initialize a sandbox in GitHub Codespaces (opens in a new tab) with a single click. By default, GitHub Codespaces shifts the cost to the user. However, organizations can be configured (opens in a new tab) to offer complimentary codespaces to users if preferred.