Introducing Speakeasy Suggest - Automatic OpenAPI Spec Maintenance

Speakeasy Suggest is an AI-powered tool designed to automate the maintenance and improvement of OpenAPI specifications, helping API companies produce high-quality and human-readable SDKs. By leveraging a Langauge Model (LLM) based agent, Speakeasy Suggest identifies and rectifies misconfigurations within OpenAPI documents, offering solutions through either the Speakeasy CLI or a GitHub workflow. This tool addresses common issues such as duplicate operationIDs, missing examples, and inline object schema redundancies by suggesting and applying JSON patches to the OpenAPI spec. The development process emphasized the need for structured output and validation of suggestions to ensure accuracy and effectiveness, ultimately favoring a custom agent approach over Retrieval Augmented Generation due to its superior handling of complex tasks. Speakeasy aims to integrate software engineering best practices into API spec management, enhancing the reliability and usability of API documentation and SDKs.