Speakeasy Suggest

Maintaining an OpenAPI schema can be time consuming, influenced by the idiosyncrasies of the server-side frameworks used to generate it, and can directly affect downstream artifacts like documentation and SDKs. Speakeasy AI-assisted maintenance will help you manage the nitty-gritty of creating a great OpenAPI document.

Speakeasy Suggest reduces the burden of spec maintenance and will eventually remove the need for you to maintain your schema at all. Add the Speakeasy Suggest GitHub workflow, and Speakeasy Suggest will automatically:

• Resolve validation errors.
• Make improvements by adding metadata.

Under the hood, Speakeasy Suggest uses the Speakeasy validator to provide validation errors as input to Speakeasy's custom LLM agent with relevant sections of the OpenAPI document.

Using the Speakeasy CLI

You can use the CLI (opens in a new tab) to instruct Speakeasy to suggest and optionally apply fixes to an OpenAPI document.

To provide example output, we'll run the following command:

Here's what this command does:

• Specifies the local filepath ~/Downloads/petstore.yaml as the OpenAPI document to make suggestions and apply fixes for.
• Limits the number of suggestions to apply to 3.
• Runs the suggestions in serial.
• Automatically applies the fixes.
• Outputs the suggested fixes to the local filepath ./test-petstore.yaml.

Below is the output of the command.

The CLI is useful for testing Speakeasy's automatic document maintenance capabilities or running in a one-off capacity with a local OpenAPI document. However, if you're looking for a long-term solution for automatically maintaining an OpenAPI document in GitHub, we recommend using the GitHub action below rather than the CLI.

To learn more about using the CLI to automatically apply fixes to an OpenAPI document, see the Speakeasy suggest documentation.

Using the GitHub Action

You can use the Speakeasy Suggest Workflow to automatically suggest and apply fixes to an OpenAPI document in GitHub via a GitHub action.

Below is a screenshot of the workflow in action.

On completion, the workflow creates a PR for the spec maintainer to review. Each PR comment will contain an error, the suggested fix, and the reasoning behind it.

Disclaimer

AI-powered automatic schema maintenance is 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!