Speakeasy Suggest
Maintaining an OpenAPI schema can be time-consuming, is influenced by the idiosyncrasies of server-side frameworks used to generate it, and directly affects downstream artifacts like documentation and SDKs. Speakeasy Suggest is an AI-powered tool that manages the details of creating excellent OpenAPI documents.
Speakeasy Suggest reduces the burden of perfecting OpenAPI documents by automatically suggesting improvements using AI. This represents the first of many AI-powered features designed to make spec maintenance easier.
Auto-fix with the Speakeasy Studio UI
The Speakeasy Studio UI provides the easiest way to get automatic suggestions. The studio interacts with local OpenAPI documents to fix issues, manage overlays, regenerate SDKs, and more.
Navigate to the Speakeasy UI (opens in a new tab) and log in. Go to the Studio tab and follow the
instructions. Alternatively, run speakeasy run --watch from the root of the SDK repo to start the Studio UI.
Refine SDK method names
By default, SDKs use OpenAPI operation IDs as method names, for example, pets.getPet(). However,
operation IDs must be globally unique, preventing SDKs from having a truly “RESTful” interface (pets.get()
and users.get() would require both operation IDs to be get). Speakeasy Suggest automatically adds Speakeasy-flavored extensions to OpenAPI documents to create consistent, accurate, and idiomatic SDK method names.
Use the Studio UI
Open the Speakeasy Studio UI following the instructions above. Click the Improve Method Names card to see the suggested fixes. After a few seconds of generating the fixes, the following appears:
Review the suggested fixes, uncheck any that shouldn’t be applied, and click Apply to apply the changes to the SDK. This creates an overlay file (opens in a new tab) and updates the Speakeasy workflow to apply it. Future SDK generations will use the overlay to include the applied changes.
Use the Speakeasy CLI
The CLI (opens in a new tab) instructs Speakeasy Suggest to improve operation IDs.
Run the following command to generate an example output:
speakeasy suggest operation-ids -s ~/Downloads/petstore.yaml -o ./updated-petstore.yaml --overlay=false
This command:
- Takes the
~/Downloads/petstore.yamlfile path of the OpenAPI document to analyze and improve - Outputs the suggested fixes to the local file path
./updated-petstore.yaml - Disables the
overlayoutput to apply the suggestions to the entire spec in the output file
Below is the output of the command:
Refine SDK error handling
SDK error handling interfaces are dictated by the granularity and accuracy of response codes defined for each
operation in the OpenAPI document.
Updating every operation’s responses can be tedious and error-prone. Speakeasy Suggest automatically adds common error
codes to OpenAPI documents and groups them into common categories, allowing users to catch specific error types. For example, 401, 403, 407, and 511 are
mapped to an Unauthorized error type in the SDK.
Use the Speakeasy CLI
The CLI (opens in a new tab) instructs Speakeasy Suggest to improve error types.
Run the following command to generate an example output:
speakeasy suggest error-types -s ~/Downloads/petstore.yaml -o ./updated-petstore.yaml --overlay=false
This command:
- Takes the
~/Downloads/petstore.yamlfile path of the OpenAPI document to analyze and improve - Outputs the suggested fixes to the local file path
./updated-petstore.yaml - Disables the
overlayoutput to apply the suggestions to the entire spec in the output file
The document updates to include new error schemas, two of which are shown below:
Each operation is updated to list the appropriate response codes and their corresponding error types:
Codes already defined elsewhere in the document are re-used. For example, if the 403 response code
is already defined with a CustomUnauthorizedResponse for one operation, it will be re-used for all operations, giving users a consistent
experience regardless of the operation being called.
Use the Studio UI
Error type suggestions are not yet available in the Studio UI.
Disclaimer
AI-powered schema suggestions are still in beta. Review suggested fixes before application to OpenAPI documents.
The accuracy of fixes suggested by Speakeasy Suggest cannot be guaranteed as the AI model and architecture are still being improved. For feedback, please join Speakeasy on Slack (opens in a new tab).