DOCSEARCHbyAlgolia
Submit Docs

Speakeasy

repository·main·Indexed 19 days ago

https://github.com/speakeasy-api/speakeasy

An OpenAPI-native toolchain that automates the generation of high-quality SDKs, Terraform providers, and contract tests from OpenAPI specifications. It includes a CLI for interacting with the toolchain and a Studio SDK for Go that provides operations for health checks, run management, overlay generation, and method name suggestions.

Tokens
34.8K
Snippets
128
Records
159
Agent score
63%

What's inside Speakeasy

  1. What is Speakeasy?

    main

    Speakeasy is a modern OpenAPI-native toolchain designed to automate the creation of high-quality API developer tools. It allows you to generate:

    • Polished SDKs: Type-safe, idiomatic code in 10+ languages (including TypeScript, Python, Go, Java, C#, PHP, Ruby, and Unity) optimized for performance and debuggability.
    • Terraform Providers: Complete providers built on a type-safe Go SDK.
    • Contract Tests: Automated test generation using a pre-built mock server (powered by Arazzo).
    • Code Samples: Clean, syncable code samples for API documentation.
    • Package Management: Tools to manage versioning and publishing to package managers (e.g., npm install your-api).
    • OpenAPI Toolchain: Advanced linting, cleaning, diffing, and editing of OpenAPI 3.X specifications (powered by Overlays).

  2. Development considerations for the Studio SDK

    main

    Maturity

    This SDK is currently in beta. Breaking changes may occur between versions without a major version update. It is highly recommended to pin your usage to a specific package version to ensure stability.

    Contributions

    This library is generated programmatically. Manual changes made to internal files will be overwritten during the next generation process. To contribute, please open a PR or an issue with a proof of concept.

  4. Handle errors in the Studio SDK

    main

    Operations return either a response or an error, never both. API errors (4XX, 5XX) typically return an sdkerrors.SDKError. You can use errors.As to check for and handle these specific error types.

    package main

import (
	"context"
	"errors"
	"github.com/speakeasy-api/speakeasy/internal/studio/sdk"
	"github.com/speakeasy-api/speakeasy/internal/studio/sdk/models/components"
	"github.com/speakeasy-api/speakeasy/internal/studio/sdk/models/sdkerrors"
	"log"
)

func main() {
	ctx := context.Background()
	s := sdk.New(sdk.WithSecurity("<YOUR_API_KEY_HERE>"))

	res, err := s.GenerateOverlay(ctx, components.OverlayCompareRequestBody{
		Before: "<value>",
		After:  "<value>",
	})
	if err != nil {
		var e *sdkerrors.SDKError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}
	}
}

  5. Use Speakeasy with AI coding agents via Agent Skills

    main

    Speakeasy can be integrated into AI coding agents using the agent-skills package. This allows agents to perform Speakeasy-specific tasks like initializing projects, validating specs, or regenerating SDKs directly within the agent's interface.

    Supported Platforms

    Skills are compatible with several major AI coding platforms, including:

    • Claude Code
    • Cursor
    • GitHub Copilot
    • Gemini CLI
    • And 15+ other platforms via agentskills.io

    Installation

    Install the skills using npx:

    npx skills add speakeasy-api/agent-skills

  7. Consume Server-sent event (SSE) streams in Go

    main

    Certain operations in the Speakeasy SDK use Server-sent events (SSE) to stream content. These operations expose the stream as an iterable object. You can consume the stream using a for loop that calls .Next() to advance through events. The loop terminates automatically when the server closes the connection.

    To use SSE:

    1. Call the streaming operation.
    2. Check if the response contains the stream object.
    3. Use defer response.Close() to ensure the connection is cleaned up.
    4. Iterate using for response.Next().
    5. Access the current event using response.Value().
    package main

import (
	"context"
	"github.com/speakeasy-api/speakeasy/internal/studio/sdk"
	"log"
)

func main() {
	ctx := context.Background()

	s := sdk.New(
		sdk.WithSecurity("<YOUR_API_KEY_HERE>"),
	)

	res, err := s.Health.Check(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.HealthResponse != nil {
		defer res.HealthResponse.Close()

		for res.HealthResponse.Next() {
			event := res.HealthResponse.Value()
			log.Print(event)
			// Handle the event
		}
	}
}

  10. Use the Speakeasy CLI

    main

    The Speakeasy CLI is a tool for interacting with the Speakeasy platform and its APIs. It allows you to:

    • Lint and validate OpenAPI specifications.
    • Manage workflows: Create, manage, and run Speakeasy workflows.
    • Configure CI/CD: Set up GitHub Actions for Speakeasy workflows.
    • Improve APIs: Suggest improvements to OpenAPI specs.
    • Generate assets from OpenAPI specs:
      • Client and Server SDKs (GO, Python, TypeScript, Java, PHP, C#, Ruby).
      • Postman collections.
      • Terraform providers.
      • MCP (Model Context Protocol) Servers.

    AI Agent Support: Run speakeasy agent context to provide structured documentation and project guidance to AI agents.

    speakeasy agent context

  11. Use the lint command to validate documents

    main
    The lint command (also aliased as validate) is a command group used to lint and validate OpenAPI documents, Speakeasy configuration files, and Arazzo documents. It provides interactive and non-interactive modes for checking specification compliance and SDK generation readiness.

  12. Use the `agent` command group

    main

    The agent command group provides specialized tools and guided workflows designed for AI coding agents to interact with Speakeasy. It includes commands for browsing embedded documentation, providing feedback, and setting up agent skills. For structured documentation specifically designed for AI consumption, run speakeasy agent context.

    speakeasy agent [command]