April 2021 Summaries

Twilio has released OpenAPI definitions for all its APIs, providing a basis for transforming these definitions into a comprehensive API Reference documentation page that updates automatically with API changes. The documentation process involves extracting API names from JSON files, creating documentation within a Twilio hub using a shell script and Github Actions, and deploying it on Bump.sh, which allows for automatic updates upon changes. This experiment is not officially endorsed by Twilio but demonstrates how to set up a centralized public page for API documentation using Bump. The setup includes categorizing documentation, customizing the user interface, and ensuring automatic updates to reflect any modifications in the API definitions, providing a streamlined and organized view of Twilio's offerings.

Bump has developed a feature called hubs to help users organize and share multiple API specifications or versions in a coherent manner. A hub serves as a centralized group of API documents, allowing users to organize their documentation in any desired format, such as by different endpoints, versions, or microservices. The process involves creating a hub from the Bump Dashboard and adding existing standalone APIs to it, which are then grouped in a root listing called "all documentations." Users can further categorize these documents using the hub category feature to distinguish between active and historical APIs, such as in the example of the JokeAPI, where the creator organized three versions of their API documentation under the hub named "Joke API Creation." This categorization ensures easy navigation and clarity for users visiting the hub, allowing them to track the evolution of the API documentation while maintaining a neat organization as the API develops further.

Bump streamlines the process of maintaining up-to-date API documentation by integrating with GitHub Actions, allowing automatic updates whenever new code is pushed to a GitHub repository. By utilizing OpenAPI and AsyncAPI specifications, Bump ensures documentation appears well-organized and aesthetically pleasing. Users need a Bump.sh account and specific credentials, such as a Doc ID and Access token, to set up the GitHub Action, which automates the documentation deployment process. After configuring the workflow, any changes committed to the repository trigger an update, making it easier for developers to manage documentation without manual uploads. This integration not only enhances efficiency but also ensures that API documentation is always current and synchronized with the latest code changes.