Speakeasy Suggest
Maintaining an OpenAPI schema can be time-consuming, is influenced by the idiosyncrasies of the server-side frameworks used to generate it, and directly affects downstream artifacts like documentation and SDKs. Speakeasy Suggest is an AI-powered tool that helps you manage the nitty-gritty of creating a great OpenAPI document.
Speakeasy Suggest reduces the burden of perfecting your OpenAPI document by automatically suggesting improvements using AI. It is the first of many AI-powered features we're developing to make spec maintenance easier.
Refine Operation IDs
Operation IDs dictate the interface your end users will interact with, both in the generated SDKs and documentation. Speakeasy Suggest refines operation IDs to make them consistent, accurate, and idiomatic.
Use the Speakeasy CLI
Use the CLI (opens in a new tab) to instruct Speakeasy Suggest to improve operation IDs.
We'll run the following command to generate an example output:
speakeasy suggest operation-ids -s ~/Downloads/petstore.yaml --style=resource -o ./updated-petstore.yaml --overlay=false
The command does the following:
- Provides the
~/Downloads/petstore.yaml
file path of the OpenAPI document to analyze and improve. - Specifies the
resource
style for operation IDs that suggests operation IDs according to resource-oriented best practices. - Outputs the suggested fixes to the local file path
./updated-petstore.yaml
. - Disables the
overlay
output to apply the suggestions to the entire spec in the output file.
Below is the output of the command:
To learn more about using the CLI to automatically apply fixes to an OpenAPI document, see the Speakeasy Suggest documentation.
Use the UI
You can also use the Speakeasy UI to suggest improved operation IDs. The underlying AI model is the same, but the UI provides an interactive experience.
Navigate to the Speakeasy UI (opens in a new tab) and log in. Go to the APIs tab and select the OpenAPI schema you want to improve.
Disclaimer
AI-powered schema suggestions are still in beta. We strongly recommend you review suggested fixes before applying them to your OpenAPI document.
We cannot guarantee the accuracy of fixes suggested by Speakeasy Suggest as we're still improving the AI model and architecture. If you have any feedback, please join Speakeasy on Slack (opens in a new tab) and let us know.