Editing Your SDK Docs

Speakeasy-managed SDKs include a README.md file. By default, the README.md file will contain at least these sections:

## 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 your SDK's methods.

Here's what it looks like put together:


  # github.com/client-sdk
  <!-- Start SDK Installation -->
  ## SDK Installation
  ```bash
  go get github.com/client-sdk
  ```
  <!-- End SDK Installation -->
  <!-- Start SDK Example 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 -->
  <!-- Start SDK Available Operations -->
  ## SDK Available Operations
  * `ListPets` - List all pets
  <!-- End SDK Available Operations -->
  <!-- Placeholder for Future Speakeasy SDK Sections -->

You can enhance your README by adding content before or after any of the three main sections (and their content) above. 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  and  comments, but the rest is up to you to maintain.

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

Remove the <!-- Start ... -> 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 that was 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 other than those shown above and add more sections in the future as new features are released or you change the configuration of your SDK via changes to your OpenAPI specification and gen.yaml configuration. These new sections will be inserted above the comment named . (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 section will be inserted here during generation, so if you do not want a section inserted, be sure to follow the steps above to convert it to a  section rather than removing it entirely.

Usage Examples

Methods

By default, the SDK README.md will include a usage example from a random operation in the OpenAPI document.

To specify one or more operations to be used as the usage example, add the x-speakeasy-usage-example extension to any operation in the OpenAPI document. Specify the usage example's response object handling with the extension x-speakeasy-usage-example: true (if the operation has more than one defined response).

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:
              x-speakeasy-usage-example: true
              schema:
                $ref: "#/components/schemas/Pets"
            application/xml:
              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/Pets"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"

This example 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.GetPetsAsync();
```

This may be particularly useful for guiding users through a specific set of instructions or a "getting started" section.

The `x-speakeasy-usage-example` configuration

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 in which they appear in the document.

Values

By default, Speakeasy will use any example values provided for schemas within your OpenAPI document when generating usage examples. If examples aren't present, Speakeasy will try to determine the most relevant example to generate from 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.

`securityschemes`

For Security Schemes, the OpenAPI specification doesn't allow you to specify examples of the values needed to populate the security details when initializing the SDKs. To provide custom examples for these values, add the x-speakeasy-example extension to the Security Scheme 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 value must be a string value and will be used as the example value for the Security Scheme. If the Security Scheme is a basic auth scheme, the example value will be a key-value pair, made up of username and password, split by a ; character, for example, YOUR_USERNAME;YOUR_PASSWORD.

Comments

Code Comments

As part of the SDK generation, the Speakeasy CLI will generate comments for Operations and Models in generated SDKs. These comments are generated from the OpenAPI specification, based on the summary or description of the Operation or Schema. Comments are generated in the target language docstring format. For example, in Python, the comments will be generated as PEP 257 (opens in a new tab)-compliant docstrings.

By default, comments are generated for all Operations and Models. To disable comment generation for your SDK, modify your gen.yaml file to disable them, like so:


# ...
generation:
  comments:
    disabled: true

Operation Comments

Comments for each method in the generated SDK will be generated from the summary or description of the Operation. For example, if you have an Operation like the following:


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 generated SDK will have a method commented like so:


// ListPets - List all pets
// Get a list of all pets in the system
func (s *SDK) ListPets(ctx context.Context) (*operations.ListPetsResponse, error) {
// ...
}

If both the summary and description are present, the summary will be used as the first line of the comment and the description will be used as the second line of the comment. If just the description is present, it will be used as the first line of the comment. If both are present but you would like to omit the description as it might be too verbose, you can use the omitdescriptionifsummarypresent option in your gen.yaml file, like so:


# ...
generation:
  comments:
    omitDescriptionIfSummaryPresent: true

Model Comments

Comments for each model in the generated SDK are generated from the description of the Schema. For example, if you have a Schema like so:


components:
  schemas:
    Pet:
      type: object
      description: A pet sold in the pet store
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

The generated SDK will have a model commented like so:


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

Per-SDK Comments

For greater control, you can configure comments that only show up in the SDK for a single language. If, for example, you need the comment for the TypeScript or Golang SDK to say something different from the others, or you want to control the documentation separately for each language, you can use the Speakeasy x-speakeasy-docs extension. Anywhere you can set the summary or description, you can add x-speakeasy-docs with per-language text for the docs.

Consider the following parameter description:


  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.

The documentation generated for each SDK will contain different comments specific to the respective programming language.

Class Names

By default, Speakeasy SDKs will be generated with the Class Name SDK. However, you can configure a custom class name by modifying your gen.yaml file to include:


generation:
  sdkClassName: "myClassName"

This will yield a package 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
}