Generate Code Comments

The Speakeasy CLI as part of its SDK generation will generate comments for Operations and Models in the generated SDKs. These comments are generated from the OpenAPI specification and are based on the summary/description of the Operations or Schemas. The comments will be generated in the target language's docstring format. For example, in Python the comments will be generated as PEP 257 compliant docstrings.

Usage

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

# ...
comments:
  disabled: true

Operation Comments

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

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:

Go

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

Python

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

Typescript

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

Java

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

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:

# ...
comments:
  omitdescriptionifsummarypresent: true

Model Comments

Comments for each model in the generated SDK will be 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:

Go

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

Python

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

Typescript

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

Java

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