SDK Documentation Quickstart

Document your API with production-ready code to make integration as easy as copy/paste. Speakeasy incorporates language-native type details and precise SDK code examples in your API reference for an IDE-like documentation experience.

We currently support seven different target outputs for SDK docs that can be combined in any way:

Target	Support	Arg
Go	✅	go
Python	✅	python
TypeScript	✅	typescript
Java	✅	java
C#	✅	csharp
Unity	✅	unity
Curl	✅	curl

Install Speakeasy

Homebrew (macOS and Linux)


brew install speakeasy-api/homebrew-tap/speakeasy

Script (macOS and Linux)


curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh

Chocolatey (Windows)


choco install speakeasy

Manual Installation

Download the latest release for your platform from the releases page (opens in a new tab), extract, and add the binary to your path.

Generate Documentation

Initialize Configs

You will need an OpenAPI spec and a gen.yaml config file to generate a new doc site directory.

Create a new gen.yaml file in your directory. Copy the language configs from your existing SDKs for each language you would like to generate docs for (curl does not require a config) and paste them into gen.yaml. For more information on where to find these gen.yaml language configurations, see the gen.yaml reference guide.

If your SDKs are published, add two additional fields to your language configs: published: true and installationURL.

Under docs, you can optionally define a defaultLanguage and a value for static (to specify whether generation presents as a static site or a Next.js server-side rendered site). This section can be left empty. For more information on possible docs configurations, see the gen.yaml reference guide.

Your starting gen.yaml config should look something like this:

gen.yaml


configVersion: 1.0.0
generation:
  comments: {}
  sdkClassName: SDK
  maintainOpenAPIOrder: true
docs:
  packageName: openapi
  static: true
  defaultLanguage: go
go:
  version: 0.0.1
  clientServerStatusCodesAsErrors: true
  flattenGlobalSecurity: true
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/sdkerrors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
  inputModelSuffix: input
  maxMethodParams: 4
  outputModelSuffix: output
  packageName: openapi
  published: true
  installationURL: github.com/speakeasy-sdks/template-speakeasy-bar
python:
  version: 0.0.1
  author: Speakeasy
  clientServerStatusCodesAsErrors: true
  description: Python Client SDK Generated by Speakeasy
  flattenGlobalSecurity: true
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
  inputModelSuffix: input
  maxMethodParams: 4
  outputModelSuffix: output
  packageName: openapi
  published: true
  installationURL: speakeasy-bar
typescript:
  version: 0.0.1
  author: Speakeasy
  clientServerStatusCodesAsErrors: true
  flattenGlobalSecurity: true
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
  inputModelSuffix: input
  maxMethodParams: 4
  outputModelSuffix: output
  packageName: openapi
  templateVersion: v2
  published: true
  installationURL: speakeasy-bar

Run Docs Generation

Run the generate docs command to generate your initial docs site directory.


speakeasy generate docs --schema ./openapi.yaml --out ./ --langs python,typescript,go,curl

Speakeasy currently doesn't support running docs as a pure static asset. You need to run with a server. If your docs site is in static site mode, the quickest way to view it is to install Go (opens in a new tab), then run the following:


pnpm i
pnpm run next:build && pnpm run export
go run server.go

Alternatively, you can run this command:


pnpm i
npm run dev

Setting Up GitHub Actions

Speakeasy provides a GitHub Actions workflow that you can set up to automatically keep your docs site repo up to date.

To use the action, create a .github/workflows/speakeasy_sdk_docs_generation.yml in your repo containing the following code:

speakeasy_sdk_docs_generation.yml


name: Generate Docs
permissions:
  checks: write
  contents: write
  pull-requests: write
  statuses: write
"on":
  workflow_dispatch:
    inputs:
      force:
        description: Force generation of SDKs
        type: boolean
        default: false
  schedule:
    - cron: 0 0 * * *
jobs:
  generate:
    uses: speakeasy-api/sdk-generation-action/.github/workflows/sdk-generation.yaml@v14
    with:
      force: ${{ github.event.inputs.force }}
      languages: |
        - docs
      docs_languages: |
        - python
        - typescript
        - go
        - curl
      mode: direct
      openapi_docs: |
        - https://{openapi_spec}.yaml
    secrets:
      github_access_token: ${{ secrets.GITHUB_TOKEN }}
      speakeasy_api_key: ${{ secrets.SPEAKEASY_API_KEY }}

Now add a SPEAKEASY_API_KEY secret to your repo.

For more information on configuring your Speakeasy generation action, see the workflow reference guide.

Documentation Structure

As SDK docs are generated, all repositories will follow a consistent structure.

gen.yaml - Place this file at the root level of your directory. It is the config that determines how your docs site will be generated.

theme.yaml - This file will be created at the root level of your directory. The settings in this file can be modified to determine how your docs site presents to the end user.

content/ - This directory is the home for generated MDX content for your docs site. It contains a pages/01-reference directory that has subfolders for each language.

content/pages/01-reference/*/resources - The resources subfolder within each language directory is the home for all your OpenAPI operations. This folder cannot be modified (any other top-level section can be modified). See custom content for more information.

src/ - This directory is the home for generated components of your docs site. Anything under this folder should not be modified directly.

public/ - This is a directory where you can make static assets available to the docs site, for example, your company logo and favicon.

next.config.js - This is the generated Next.js config for the docs site.

Dockerfile - This is a Dockerfile Speakeasy will always generate to assist with hosting your docs-site server.

server.go - If you are generating docs as a static site, Speakeasy provides this convenient Go server to host your static site.