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:
brew install speakeasy-api/homebrew-tap/speakeasy
curl -fsSL https://raw.githubusercontent.com/speakeasy-api/speakeasy/main/install.sh | sh
choco install speakeasy
Download the latest release for your platform from the releases page (opens in a new tab), extract, and add the binary to your path.
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
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.
gen.yaml config should look something like this:
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 ipnpm run next:build && pnpm run exportgo run server.go
Alternatively, you can run this command:
pnpm inpm run dev
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:
Now add a
SPEAKEASY_API_KEY secret to your repo.
For more information on configuring your Speakeasy generation action, see the workflow reference guide.
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.