Skip to main content

Generate Readmes

The SDK Generator will generate a file and attempt to keep it up to date with the latest changes to the SDK. A file will be generated from scratch if one does not exist. If one does exist, the generator will attempt to update it with the latest changes to the SDK. The generator will not overwrite any changes you have made to the file.

The file will contain various sections as seen in the example below:


<!-- Start SDK Installation -->
## SDK Installation
go get
<!-- End SDK Installation -->

<!-- Start SDK Example Usage -->
## SDK Example Usage
package main
<!-- End SDK Example Usage -->

import (


func main() {
ctx := context.Background()

opts := []sdk.SDKOption{
APIKey: shared.SchemeAPIKey{

s := sdk.New(opts...)

res, err := s.ListPets(ctx)
if err != nil {

if res.Pets != nil {
// handle response

<!-- Start SDK Available Operations -->
## SDK Available Operations
* `ListPets` - List all pets
<!-- End SDK Available Operations -->

The README can be modified by adding additional content before or after any of the three main sections (and their content) above:

  • ## SDK Installation - A 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 - A list of all the generated operations from the OpenAPI document.

The generator will not overwrite any content you have added to the file. The generator will only update the content within the three main sections above.

If your would like to modify any of the autogenerated sections above, and not have them overwritten on the next generation you can remove the <!-- Start {SECTION_NAME} --> and <!-- End {SECTION_NAME} --> comments from the file. The generator will only overwrite the content between these comments.

Usage Examples

The SDK Generator by default will generate a usage example from a random operation in the OpenAPI document. If you would like to specify a specific operation to use as the usage example, you can add the x-speakeasy-usage-example extension to the operation in the OpenAPI document, and the same extension to a response content object to use as the example response. For example:

x-speakeasy-usage-example: true
summary: List all pets
operationId: ListPets
- pets
description: A paged array of pets
x-speakeasy-usage-example: true
$ref: '#/components/schemas/Pets'