Editing SDK docs
Speakeasy-managed SDKs include a README.md
file that contains at least the following sections by default:
## Summary
: A brief introduction based on theinfo
andexternalDocs
attributes defined in the OpenAPI document.## Table of Contents
: A list of links to all available sections in the README.## SDK Installation
: An installation snippet based on the package name provided in thegen.yaml
file.## SDK Example Usage
: An example usage snippet based on the first operation in the OpenAPI document.## SDK Available Operations
: Links to documentation that covers all the SDK’s methods.
Here’s what it looks like put together:
# github.com/client-sdk<!-- Start Summary [summary] -->## Summary<The `info.summary` provided in your OpenAPI specification><The `info.description` provided in your OpenAPI specification>For more information about the API: [<externalDocs.description>](externalDocs.url)<!-- End Summary [summary] --><!-- Start Table of Contents [toc] -->## Table of Contents<!-- $toc-max-depth=2 -->* [OpenAPI SDK](#openapi-sdk)* [SDK Installation](#sdk-installation)* [SDK Example Usage](#sdk-example-usage)* [Available Resources and Operations](#available-resources-and-operations)* ...* [Development](#development)* [Maturity](#maturity)* [Contributions](#contributions)<!-- End Table of Contents [toc] --><!-- Start SDK Installation [installation] -->## SDK Installation```bashgo get github.com/client-sdk```<!-- End SDK Installation [installation] --><!-- Start SDK Example Usage [usage] -->## SDK Example Usage```gopackage mainimport ("context""fmt""log""os""github.com/client-sdk""github.com/client-sdk/pkg/models/shared""github.com/client-sdk/pkg/models/operations")func main() {ctx := context.Background()opts := []sdk.SDKOption{sdk.WithSecurity(shared.Security{APIKey: shared.SchemeAPIKey{APIKey: "YOUR_API_KEY",},}),}s := sdk.New(opts...)res, err := s.ListPets(ctx)if err != nil {log.Fatal(err)}if res.Pets != nil {// handle response}}```<!-- End SDK Example Usage [usage] --><!-- Start SDK Available Operations [operations] -->## SDK Available Operations- `ListPets` - List all pets<!-- End SDK Available Operations [operations] --><!-- Placeholder for Future Speakeasy SDK Sections -->
The README can be enhanced by adding content before or after any of the three main sections (SDK Installation, SDK Example Usage, and SDK Available Options). The generator will not overwrite any content added to the README.md
file. The generator automatically keeps the content within the walled-off sections between the <!-- Start ... [tag] -->
and <!-- End ... [tag] -->
comments, but the rest requires manual maintenance.
To take over the management of automatically generated sections:
- Remove the
<!-- Start ... [tag] -->
section comment. - Find the matching
<!-- End ... [tag] -->
comment and change it to<!-- No ... [tag] -->
, which marks that section as manually managed. (This step is important. If only the “Start” comment is removed, the section may be re-inserted, as described below.) - Edit the content between those comments as needed.
To revert back to Speakeasy-managed sections, either delete the <!-- No ... [tag] -->
comment from the file, or replace it with <!-- Start ... [tag] --><!-- End ... [tag] -->
, and the next generation will re-insert the Speakeasy-managed content into the file.
Speakeasy may provide additional sections as new features are released or when SDK configuration is altered by changing the OpenAPI document and gen.yaml
configuration. These new sections are inserted above the <!-- Placeholder for Future Speakeasy SDK Sections -->
comment. (The placeholder heading will always be present in the file, and if removed, it will be added again just below the last README section.) Any missing sections will be inserted here during generation, so to prevent a section from being inserted, follow the steps above to convert it to a <!-- No ... [tag] -->
section rather than removing it entirely.
Usage examples
Main usage section
By default, USAGE.md
and the SDK Example Usage section in the main README.md
file showcase a usage example from a random operation in the OpenAPI document. To specify one or more operations to be used as the main usage example, set the x-speakeasy-usage-example: true
extension to any operation in the OpenAPI document.
The x-speakeasy-usage-example
extension can be further configured to associate each usage snippet with a custom header, description, and relative positioning.
Key | Description |
---|---|
title | The title text to be used for the usage example (an empty string indicates no title). |
description | The description for the usage example (an empty string indicates no description). |
position | Usage examples are sorted from lowest to highest based on the position value. Usage examples that share a position value will be sorted in the order they appear in the document. |
This is particularly useful for guiding through a specific set of instructions or a “getting started” section. For example:
paths:/pets:get:x-speakeasy-usage-example:title: List the petsdescription: Now you can get all of the pets that have been added.position: 2summary: List all petsoperationId: ListPetstags:- petsresponses:"200":description: OKcontent:application/json:schema:$ref: "#/components/schemas/Pets"put:x-speakeasy-usage-example:title: Add your petdescription: First, add your own pet.position: 1summary: Add petoperationId: AddPettags:- petsrequestBody:content:application/json:schema:$ref: "#/components/schemas/Pet"responses:"200":description: OK
This YAML will result in the following being added to the README.md
and USAGE.md
files:
### Add your petFirst, add your own pet.```csharpusing PetStore;using PetStore.Models.Pets;var sdk = new PetstoreSDK();var req = new Pet();var res = await sdk.Pets.AddPetAsync(req);```### List the petsNow you can get all of the pets that have been added.```csharpusing PetStore;using PetStore.Models.Pets;var sdk = new PetstoreSDK();var res = await sdk.Pets.ListPetsAsync();```
Table of contents
To generate a more detailed table of contents, adjust the value of the $toc-max-depth
parameter in the README.md
file. Subheadings will be updated on regeneration:
<!-- $toc-max-depth=3 -->* [openapi](#openapi)* [SDK Installation](#sdk-installation)* [SDK Example Usage](#sdk-example-usage)* [Example 1](#example-1)* [Example 2](#example-2)* [Example 3](#example-3)* [Custom Header](#custom-header)* ...
When adding sections to the README.md
file manually, follow basic Markdown syntax to ensure custom headings are properly referenced:
## Section Heading (level 2)### Subsection Heading (level 3)...
Feature sections
Specific usage snippets can be selected for other sections in the main README.md
, as long as they effectively showcase the feature. The x-speakeay-usage-example
extension can specify a list of section tags
(referring to <-- Start Section [tag] -->
placeholders).
For example, to select an operation for both the Override Server URL Per-Operation and the Retries sections:
/webhooks/subscribe:post:operationId: subscribeToWebhooksservers:- url: https://speakeasy.barx-speakeasy-usage-example:tags:- server- retriesx-speakeasy-retries:strategy: backoffbackoff:initialInterval: 10maxInterval: 200maxElapsedTime: 1000exponent: 1.15
The table below lists the supported tags
and their conditions.
README section | Sub-section | tag | Conditions for selection to be effective |
---|---|---|---|
Global parameters | global-parameters | One of the parameters must originate from x-speakeasy-globals . | |
Event streaming | eventstream | One of the responses must use the text/event-stream content type. | |
Pagination | pagination | x-speaskeasy-pagination must be set for the operation. | |
Retries | retries | x-speakeasy-retries must be set for the operation. | |
Error handling | errors | One of the responses must be an error with custom content data. | |
Server selection | Per-client | server | servers must not be set at the operation level. |
Server selection | Per-operation | server | Operation must define its own servers array. |
Authentication | Per-client | security | security must not be set for the operation. |
Authentication | Per-operation | security | Operation must define its own security array. |
SDK example usage | usage | None (same effect as x-speakeasy-usage-example: true ). |
The usage
tag can select an operation for both the main usage section and other sections:
/drinks/{page}:get:operationId: listDrinksx-speakeasy-pagination:type: offsetLimitinputs:- name: pagein: parameterstype: pagex-speakeasy-usage-example:title: "Browse available drinks"position: 2tags:- usage- pagination
Note that title
, description
, and position
attributes only affect the main SDK Example Usage section.
Values
When generating usage examples, Speakeasy defaults to using any example
values provided for schemas in the OpenAPI document. If no examples are present, Speakeasy tries to determine the most relevant example to generate from either the format
field of a schema or the property name of a schema in an object. For example, if the schema has format: email
or is within a property called email
, Speakeasy generates a random email address as an example value.
Security schemes
The OpenAPI Specification does not allow specifying example values for security schemes when initializing SDKs. Custom examples can be provided by adding the x-speakeasy-example
extension to the securitySchemes
section in the OpenAPI document, for example:
components:securitySchemes:apiKey:type: apiKeyname: api_keyin: headerx-speakeasy-example: YOUR_API_KEY
The x-speakeasy-example
must be a string and will be used as the example value for the security scheme. For basic auth security schemes, the example value will be a key-value pair consisting of a username and password separated by a ;
, for example, YOUR_USERNAME;YOUR_PASSWORD
.
Comments
Code comments
The Speakeasy CLI adds comments for operations and models in generated SDKs, based on the summary or description of each operation or schema in the OpenAPI document. Comments are generated using the docstring format of the target language. For example, in Python, comments are generated as PEP 257 (opens in a new tab)-compliant docstrings.
By default, comments are generated for all operations and models. Comment generation for an SDK can be disabled in the gen.yaml
file:
# ...generation:comments:disabled: true
Operation comments
Comments for each method in the generated SDK will be based on the operation’s summary or description. For example, given an operation defined as follows:
paths:/pets:get:operationId: listPetssummary: List all petsdescription: Get a list of all pets in the systemresponses:"200":description: A list of petscontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Pet"
The corresponding method in the generated SDK is commented like this:
// ListPets - List all pets// Get a list of all pets in the systemfunc (s *SDK) ListPets(ctx context.Context) (*operations.ListPetsResponse, error) {// ...}
If only a description is present, it will be used as the first line of the comment. If both a summary and description are provided, the summary will be used as the first line of the comment and the description as the second. When both are present, the description can be omitted using the omitDescriptionIfSummaryPresent
option in the gen.yaml
file:
# ...generation:comments:omitDescriptionIfSummaryPresent: true
Model comments
Comments for each model in the SDK are generated from the description of the schema. For example, given the following schema:
components:schemas:Pet:type: objectdescription: A pet sold in the pet storeproperties:id:type: integerformat: int64name:type: string
The corresponding model in the generated SDK is commented like this:
// Pet// A pet sold in the pet storetype Pet struct {// ...
Per-SDK comments
Comments can be configured to appear only in the SDK for a single language. For example, comments for the TypeScript or Go SDKs might need to differ from those in other languages, or documentation might need to be controlled separately for each language.
The x-speakeasy-docs
extension can be added to any section that includes a summary
or description
to include per-language documentation:
parameters:- name: typein: querydescription: This query parameter names the type of drink to filter the results by. If not provided, all drinks will be returned.required: falseschema:$ref: "#/components/schemas/DrinkType"x-speakeasy-docs:go:description: The type field names the type of drink to filter the results by. If set to nil, all drinks will be returned.python:description: The ``type`` field names the type of drink to filter the results by. If set to ``None``, all drinks will be returned.typescript:description: This field is the type of drink to filter the results by. If set to null, all drinks will be returned.
Each SDK’s documentation will include comments specific to its programming language.
Class names
By default, Speakeasy SDKs are generated with the class name SDK
. A custom class name can be configured by modifying the gen.yaml
file as follows:
generation:sdkClassName: "myClassName"
The generated package looks like this:
package petshopimport ("net/http""openapi/pkg/utils")var ServerList = []string{"http://petstore.speakeasy.io/v1",}type HTTPClient interface {Do(req *http.Request) (*http.Response, error)}type PetShop struct {Pets *Pets_defaultClient HTTPClient_securityClient HTTPClient_serverURL string_language string_sdkVersion string_genVersion string}