Document Your SDK
Speakeasy-managed SDKs include a README.md file. By default, the README.md file will contain the following sections:
## SDK Installation- A installation snippet based on the package name provided in thegen.yamlfile.## 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
<!-- End SDK Example Usage -->
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
}
}
```
<!-- Start SDK Available Operations -->
## SDK Available Operations
* `ListPets` - List all pets
<!-- End SDK Available Operations -->
You can enhance your README by making choices about the content by adding additional 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 only update the content within the three main sections above.
If your would like to modify any of the auto-generated 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 README.md file. The generator will only overwrite the content between these comments.
Usage Examples
Methods
By default, the SDK's README.md will include a usage example from a random operation in the OpenAPI document.
To specify a particular operation to be used as the usage example, you can add the x-speakeasy-usage-example extension to the relevant operation in the OpenAPI document. The usage example's response object handling can also be specified with the same extension (if the operation has more than one).
For example:
paths:
/pets:
get:
x-speakeasy-usage-example: true
summary: List all pets
operationId: ListPets
tags:
- pets
responses:
"200":
description: A paged array of pets
content:
application/json:
x-speakeasy-usage-example: true
schema:
$ref: "#/components/schemas/Pets"
application/xml:
schema:
$ref: "#/components/schemas/Pets"
Values
By default when generating usage examples we will use any example values provided for schemas within your OpenAPI document. If examples aren't present we 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 we will generate a random email address as an example value.
For Security Schemes, the OpenAPI specification doesn't allow specify examples for the values needed to populate the security details when initializing the SDKs. To allow you to provide custom examples for these values, you can 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
x-speakeasy-example just needs to 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 for the username and password split by a ; character. For example: YOUR_USERNAME;YOUR_PASSWORD.
## 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](https://www.python.org/dev/peps/pep-0257/) compliant docstrings.
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:
```yaml
# ...
generation:
comments:
disabled: true
Comments
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) {
// ...
}
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() {
// ...
}
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 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 {
// ...
@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 {
// ...
Class Names
By default The Speakeasy SDKs will be generated with the Class Name SDK. However a custom class name can be configured by modifying your gen.yaml file to include:
generation:
sdkClassName: "myClassName"
Yields a package like:
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
}