July 2025 Summaries

OpenAPI 3.2 is an upcoming release that promises full backward compatibility with version 3.1, bringing several requested improvements and enhancements without causing compatibility issues. Previous version 3.1, released in 2021, marked significant advancements by aligning OpenAPI with JSON Schema 2020-12, which reduced editing and sharing API schema friction and improved support for asynchronous APIs via webhooks. OpenAPI 3.2 is set to introduce new features such as the OAuth 2.0 Device Authorization Grant, the deprecation of certain security schemes, tag summaries for better display, and support for all HTTP methods, including custom and non-standard ones. It will also officially support sequential JSON formats, enhancing flexibility in handling data. Despite being a minor update, OpenAPI 3.2 addresses community requests and is anticipated to be released in the summer, with comprehensive guides available to facilitate its adoption.

Bump.sh has introduced Bump.sh Embed, a new solution aimed at integrating API documentation seamlessly into a company's website, akin to the approaches used by industry leaders like Square, Twilio, and Stripe. Traditionally, API documentation is hosted separately, creating a disjointed user experience, but Bump.sh Embed offers full control over design, routing, and user interface, allowing companies to integrate API docs as part of their main site without any friction. This tool enables enterprises to maintain branding, apply their design systems, and integrate custom features such as search engines and analytics, all while ensuring the documentation remains SEO-ready and fully customizable. By leveraging existing infrastructure like reverse proxies, Bump.sh Embed allows for seamless integration without needing to overhaul existing systems, and it promises a future where API documentation can be embedded more dynamically within product flows, supporting various formats and enhanced integration with content systems and automation tools. The service is currently available for enterprise customers, positioning Bump.sh as a potential leader in providing headless API documentation solutions.

Bump.sh emerged as a solution to the critical issue of poorly maintained API documentation, illustrated by a real-life incident where an evolving API without updated documentation caused an e-commerce site with a million users to freeze at checkout. The narrative underscores the importance of comprehensive and up-to-date API documentation in preventing user dissatisfaction and operational disruptions, emphasizing that inadequate documentation can lead users to abandon products and escalate support tickets. The text highlights the necessity of regular audits and updates on API documentation to enhance user experience, reduce support burdens, and improve brand image. By providing user-centered documentation, companies can ensure smoother onboarding, increased feature adoption, and higher developer engagement. Bump.sh advocates for proactive documentation management, offering expert guidance to optimize API documentation processes, as illustrated by successful case studies like Stripe and BigID.

Bump.sh and Microcks can be effectively combined to optimize the API lifecycle by enabling a seamless process of documentation, simulation, and testing. Bump.sh transforms OpenAPI and AsyncAPI descriptions into comprehensive API reference documentation, while Microcks provides a platform for simulating APIs and testing API implementations against their descriptions, ensuring accuracy and consistency. This integration fosters a design-first workflow, allowing teams such as iOS developers to work concurrently with API development, significantly reducing time and costs. By using mock servers, both teams can identify and address potential issues early in the process, facilitating rapid iterations and feedback cycles. The collaborative approach allows for quicker adjustments to API descriptions, enhancing flexibility and reliability. Companies like J.B. Hunt Transport Services have reported substantial time savings by employing Microcks to power mock servers. Additionally, Microcks serves as a testing tool to verify that an API implementation aligns with its description, providing a compliance check that helps maintain consistency and accuracy in API documentation and functionality.

Apiary.io, a pioneering platform in API documentation since 2011, is closing down following its acquisition by Oracle in 2017, which has been transitioning users to Oracle Cloud—a service criticized for its complexity and cost transparency. Originally known for introducing the Markdown-based API Blueprint format and tools like Dredd and Gavel, Apiary played a key role in the API Design-first workflow but eventually supported the more widely adopted OpenAPI format. As Apiary plans to shut down fully by September 2025, Bump.sh emerges as a recommended successor, offering seamless Git integrations, support for OpenAPI v3.1, and additional features like AsyncAPI and Webhooks, thus providing a straightforward, user-friendly solution for API documentation needs. Bump.sh also offers tools for converting and upgrading API documentation from Apiary, ensuring a smooth transition for users.