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: Speakeasy suggest output

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.

Speakeasy suggest UI

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.