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
- A installation snippet based on the package name provided in thegen.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 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 automatically keep the content within the walled off sections between the <!-- Start ... -->
and <!-- End ... -->
comments, but the rest is up to you to maintain.
If you would like to take over management of the automatically generated sections, then you can do the following:
- Remove the
<!-- Start ... ->
section comment. - Find the matching
<!-- End ... -->
section and change it to<!-- No ... -->
, which marks that section as managed by you. (This step is important. If you simply remove the "Start" comment, the section may re-inserted as described below.) - Edit the content that was between those comments as you see fit.
If, at any time, you change your mind and want to go back to having Speakeasy manage a section, you can either delete the <!-- No ... -->
comment from the file or you can replace it with <!-- Start ... --><!-- End ... -->
and the next generation will insert the Spekeasy-managed content back into your file.
Speakeasy may provide other sections other than those shown above and will 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 <!-- Placeholder for Future Speakeasy SDK Sections -->
. (This heading will always be present in the file and if you remove it, it will be added again just below the last readme section in the file.) 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 for converting it to a <!-- No ... -->
section rather than removing it entirely.
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 one or more operations to be used as the usage example, you can add the x-speakeasy-usage-example
extension to any operation in the OpenAPI document. The usage example's response object handling can also be specified 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"
will result in the following being added to the README.md
and USAGE.md
:
## Add your petFirst, add your own pet```csharpusing PetStore;using PetStore.Models.Pets;var sdk = new PetstoreSDK();var req = new Pet();var res = await sdk.Pets.AddPetAsync(req);```## List the petsNow you can get all of the pets that have been added```csharpusing 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 lowest-to-highest based on 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 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.
securityschemes
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 CommentsThe 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 systemfunc (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 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 storetype Pet struct { // ...
Per-SDK Comments
For even 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 want to control the documentation separately for each, Speakeasy provides a tool for this purpose via the x-speakeasy-docs
extension. Anywhere you can set the summary
or description
, you can also add x-speakeasy-docs
with per-language 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 reuslts 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 drink will be returned.
This will result in the documentation generated for Go, Python, and TypeScript SDKs each being different.
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 petshopimport ( "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}