SDK Sandboxes

Speakeasy can generate dev container configurations for your SDK repositories to give you and your SDK consumers an intuitive, predefined sandbox environment to explore the capabilities of your SDK. 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, you’ll need to make minor adjustments to your gen.yaml file. The schemaPath shown below should reference your 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

Your 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, you have the option to configure your organization (opens in a new tab) to offer complimentary codespaces to your users if you prefer.