Skip to main content

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:

// 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:

# ...
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:

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