The challenge: Deliver an automated, more accurate API documentation process for customers
Elastic provides a robust suite of APIs that power its platform for search, analysis, and data management.
Elastic’s rapidly growing API ecosystem required a unified, accurate, and automated documentation platform to meet user expectations and effectively support development workflows.
What Elastic was looking for
Elastic needed a documentation platform capable of addressing the unique requirements of our APIs.
These requirements included:
- Comprehensive OpenAPI (OAS) support: The ability to handle large, deeply nested, and complex OAS files while ensuring accuracy.
- Customizability: Support for custom extensions related to the API lifecycle and the ability to integrate with Elastic’s existing website search.
- User-friendly and performant: An appealing layout, fast search capabilities, and a seamless user experience for developers.
- Automation features: Automated changelogs to streamline updates and improve transparency.
The solution: Bump.sh API documentation platform
By partnering with Bump.sh, Elastic transformed its approach to API documentation.
- Unified API documentation: Elastic consolidated its API docs into a single, user-friendly reference site, ensuring a consistent experience for users.
- Automated and accurate updates: Bump.sh enabled Elastic to automate the generation and validation of OAS files directly from code, minimizing errors and ensuring documentation is always up to date.
- Responsive support: Bump.sh’s enthusiastic assistance helped Elastic meet tight deadlines, launch documentation for a new product, and deliver a seamless integration into its website search.
The results: Streamlined documentation and enhanced developer experience
The partnership with Bump.sh delivered tangible improvements to Elastic’s API documentation.
Improvements include:
- Faster updates and better accuracy: Automating the OAS generation process ensured Elastic’s documentation stayed in sync with rapid API changes.
- Improved usability: A modern, intuitive interface enabled users to quickly locate the information they needed, reducing friction in the development process.
- Scalability: Elastic successfully published detailed API documentation for a new product on a tight timeline, demonstrating the platform’s ability to handle growth and complexity.
Note from the Bump.sh team
Elastic came to us with a unique challenge. The depth of their OpenAPI definition files made them some of the most challenging to render on the market (3.9Mb - 91k lines of JSON for the Elasticsearch Serverless API).
None of the traditional OpenAPI renderers could tackle it at once. Only the Bump.sh server-side parsing technology could make it, while still:
- optimizing rendering performance and load times
- optmizing SEO with auto-generated sitemaps
- making it possible for the Elastic dev portal search to ingest the sitemaps, offering a seamless search experience across all docs and the API reference pages powered by Bump.sh
👉 This is a real game changer. Until now, many API publishers had to cobble together custom pipelines to get around renderer limits: splitting massive OpenAPI files into smaller ones, or even converting them into Markdown before publishing. But those workarounds break the promise of OpenAPI, create extra maintenance overhead, and ultimately add friction for both the teams building APIs and the engineers using them.
As our Head of PM says:
By tackling the parsing and rendering of even the most complex definition files on the market, and offering optimal page load times and developer experience, Bump.sh directly supports OpenAPI adoption, enabling it to deliver the promise: be the source of truth, the API contract that humans and machines can refer to.
Metrics
- Documentation accuracy improved dramatically, reducing errors caused by manual updates.
- Internal maintenance time decreased, allowing Elastic teams to focus on product development instead of managing content delivery.
Timeframe
Elastic’s transformation began upon adopting Bump.sh and achieved full implementation within seven months. This timeframe included the migration of existing documentation, automation of OAS generation, and integration into Elastic’s website search.
Partnering with Bump.sh has been a game-changer for our API documentation. By automating the content delivery process and consolidating all API references into a single platform, we’ve improved accuracy, usability, and scalability—freeing up our teams to focus on what they do best. The result is a developer experience that we’re proud to provide.
The journey and what’s next
Elastic’s collaboration with Bump.sh has been pivotal in delivering a unified and automated API documentation platform. By addressing previous challenges and streamlining the documentation process, Elastic now provides developers with a seamless experience that accelerates innovation.
Moving forward, Elastic is continuing to enhance its documentation pipeline, building on the strong foundation established with Bump.sh to further refine and expand its developer resources.
