Speakeasy Suggest

Maintaining an OpenAPI schema can be time consuming, idiosyncratic to the server side frameworks being used to generate it, and have direct impact on downstream artifacts like documentation and SDKs. To help you manage the nitty-gritty of creating a great OpenAPI document, we provide AI-assisted maintenance.

Speakeasy Suggest will help you reduce the burden of spec maintenance and eventually remove the need to maintain it at all by just adding our Github workflow. Speakeasy Sugges 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 along with relevant sections of the OpenAPI document.

CLI

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

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

speakeasy suggest -s ~/Downloads/petstore.yaml -n 3 -o ./test-petstore.yaml --serial -a true

This uses the local filepath, ~/Downloads/petstore.yaml as the OpenAPI document to suggest and apply fixes for, limits the number of suggestions to apply at 3, runs the suggestions in serial, automatically applies the fixes, and outputs the suggested fixes to the local filepath, ./test-petstore.yaml.

Below is the output of the above command. Speakeasy suggest output

The CLI is good for testing out Speakeasy's automatic document maintenance capabilities, or running in a one-off capacity with a local OpenAPI document. However, it's not ideal as a long-term solution for automatically maintaining an OpenAPI document in Github. For that, we recommend using the action below.

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

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. Speakeasy Suggest Workflow

This will result in a PR for the spec maintainer to review. PR comments will each contain the error the suggestion is fixing, the suggested fix, and an explanation of why that fix was suggested. Speakeasy Suggest PR

Disclaimer

AI-powered automatic schema maintenance is still in Beta. We strongly recommend reviewing the suggested fixes before applying them to your OpenAPI document. Accuracy of the fixes cannot be guaranteed as we're still working on improving the AI model/architecture. If you have any feedback, please join Speakeasy on Slack (opens in a new tab) and let us know!