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 the info and externalDocs 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 the gen.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

```bash
go get github.com/client-sdk
```

  <!-- End SDK Installation [installation] -->

  <!-- Start SDK Example Usage [usage] -->

## SDK Example Usage

```go
package main

import (
    "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 -->

You can enhance your README 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 you have added to the README.md file. The generator will automatically keep the content within the walled-off sections between the  and  comments, but the rest is up to you to maintain.

If you would like to take over the management of automatically generated sections, you can do the following:

Remove the  section comment.
Find the matching  comment and change it to , which marks that section as managed by you. (This step is important. If you only remove the “Start” comment, the section may be re-inserted, as described below.)
Edit the content between those comments as you see fit.

If you change your mind at any time and want to go back to having Speakeasy manage a section, you can either delete the  comment from the file, or replace it with , and the next generation will re-insert the Speakeasy-managed content into your file.

Speakeasy may provide additional sections as new features are released or as you alter your SDK configuration by changing your OpenAPI document and gen.yaml configuration. These new sections will be inserted above the  comment. (The placeholder heading will always be present in the file, and if you remove it, it will be added again just below the last README section.) Any missing sections will be inserted here during generation, so if you do not want a section inserted, follow the steps above to convert it to a  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 will showcase a usage example from a random operation in the OpenAPI document. You can specify one or more operations to be used as the main usage example by setting 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 may be particularly useful for guiding users through a specific set of instructions or a “getting started” section. For example:

paths:
  /pets:
    get:
      x-speakeasy-usage-example:
        title: List the pets
        description: Now you can get all of the pets that have been added.
        position: 2
      summary: List all pets
      operationId: ListPets
      tags:
        - pets
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
    put:
      x-speakeasy-usage-example:
        title: Add your pet
        description: First, add your own pet.
        position: 1
      summary: Add pet
      operationId: AddPet
      tags:
        - pets
      requestBody:
        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 pet

First, add your own pet.

```csharp
using PetStore;
using PetStore.Models.Pets;

var sdk = new PetstoreSDK();

var req = new Pet();

var res =  await sdk.Pets.AddPetAsync(req);
```

### List the pets

Now you can get all of the pets that have been added.

```csharp
using PetStore;
using PetStore.Models.Pets;

var sdk = new PetstoreSDK();
var res =  await sdk.Pets.ListPetsAsync();
```

To generate a more detailed table of contents, edit 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 manually adding sections to your README.md file, respect basic Markdown syntax to ensure custom headings are properly referenced:

## Section Heading (level 2)
### Subsection Heading (level 3)
...

Feature sections

You can select specific usage snippets for other sections in the main README.md, as long as they effectively showcase the feature. Use the x-speakeay-usage-example extension and 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, you can use the following:

/webhooks/subscribe:
  post:
    operationId: subscribeToWebhooks
    servers:
      - url: https://speakeasy.bar
    x-speakeasy-usage-example:
      tags:
        - server
        - retries
    x-speakeasy-retries:
      strategy: backoff
      backoff:
        initialInterval: 10
        maxInterval: 200
        maxElapsedTime: 1000
        exponent: 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`).

Use the usage tag to select an operation for the main usage section as well as other sections:

/drinks/{page}:
  get:
    operationId: listDrinks
    x-speakeasy-pagination:
      type: offsetLimit
      inputs:
        - name: page
          in: parameters
          type: page
    x-speakeasy-usage-example:
      title: "Browse available drinks"
      position: 2
      tags:
        - 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 your OpenAPI document. If no examples are present, Speakeasy will try 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 will generate a random email address as an example value.

Security schemes

The OpenAPI Specification does not allow you to specify example values for security schemes when initializing SDKs. Provide custom examples by adding the x-speakeasy-example extension to the securitySchemes section in your OpenAPI document, for example:

components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: api_key
      in: header
      x-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. Disable comment generation for an SDK 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: listPets
      summary: List all pets
      description: Get a list of all pets in the system
      responses:
        "200":
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $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 system
func (s *SDK) ListPets(ctx context.Context) (*operations.ListPetsResponse, error) {
// ...
}

def list_pets(self) -> operations.ListPetsResponse:
    r"""List all pets
    Get a list of all pets in the system
    """
    # ...

  /**
   * ListPets - List all pets
   *
   * Get a list of all pets in the system
  **/
  ListPets(
    config?: AxiosRequestConfig
  ): Promise<operations.ListPetsResponse> {
    // ...
  }

  /**
   * ListPets - List all pets
   *
   * Get a list of all pets in the system
  **/
  public ListPetsResponse listPets() {
    // ...
  }

  /// <summary>
  /// List all pets
  ///
  /// <remarks>
  /// Get a list of all pets in the system
  /// </remarks>
  /// </summary>
  Task<ListPetsResponse> ListPetsAsync();

Note: In C#, the operation comment will appear on the function definition on the interface, not the class itself.

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, you may prefer to omit the description 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: object
      description: A pet sold in the pet store
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

The corresponding model in the generated SDK is commented like this:

// Pet
// A pet sold in the pet store
type Pet struct {
    // ...

@dataclass_json
@dataclass
class Pet:
    r"""Pet
    A pet sold in the pet store
    """
    # ...

// Pet
/**
 * A pet sold in the pet store
**/
export class Pet extends SpeakeasyBase {
    // ...

/**
 * Pet
 *
 * A pet sold in the pet store
**/
public class Pet {
    // ...
}

/// <summary>
/// A pet sold in the pet store
/// </summary>
public class Pet {
    // ...
}

Per-SDK comments

You can configure comments to appear only in the SDK for a single language. For example, you may need comments for the TypeScript or Go SDKs to differ from those in other languages, or to control the documentation separately for each language.

You can add the x-speakeasy-docs extension to any section that includes a summary or description, and use it to include per-language documentation:

parameters:
  - name: type
    in: query
    description: This query parameter names the type of drink to filter the results by. If not provided, all drinks will be returned.
    required: false
    schema:
      $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. You can configure a custom class name by modifying the gen.yaml file as follows:

generation:
  sdkClassName: "myClassName"

The generated package looks like this:

package petshop

import (
	"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
}