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:

TargetSupportArg
Gogo
Pythonpython
TypeScripttypescript
Javajava
C#csharp
Unityunity
Curlcurl

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
speakeasy_version: latest
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.