This content originally appeared on DEV Community and was authored by Paul B.
This week, Twilio published OpenAPI definitions for all of their APIs. Let's see together the small steps we can take to transform those definitions into a nice looking API Reference documentation page which tracks API changes automatically.
If you wonder what Twilio is, here's a paragraph taken from their about page:
Twilio has democratized communications channels like voice, text, chat, video, and email by virtualizing the world’s communications infrastructure through APIs that are simple enough for any developer to use, yet robust enough to power the world’s most demanding applications.
Note: this is an experiment demonstration which is not endorsed, nor affiliated by, the Twilio company.
Definition files hierarchy
First let's take a look at the repository with their published files. The OpenAPI definition files are available in the spec/ folder in both JSON or YAML formats. Here's a sneak peek of some of the JSON files available:
spec/
└── json/
├── twilio_accounts_v1.json
├── twilio_chat_v2.json
├── twilio_conversations_v1.json
├── twilio_events_v1.json
├── twilio_fax_v1.json
├── twilio_messaging_v1.json
├── twilio_notify_v1.json
├── twilio_numbers_v2.json
├── twilio_verify_v2.json
├── twilio_video_v1.json
├── twilio_voice_v1.json
└── …
At first glance we can imagine a quick way of generating the documentation pages:
- For each file from the available
*.jsonfiles- Extract the API name from filename
twilio_<api_name>_vN.json - Create documentation
api_namefrom the api definition filetwilio_<api_name>_vN.jsonwithin a single Hub named Twilio
- Extract the API name from filename
- Enjoy the result and customise the UI!
Automatically publish the documentation on changes
In order to demonstrate the magic on each commit I've forked their repository on my Github namespace where I will be able to push to my main branch and use Github Actions on my fork.
Now let's write a tiny shell script - Don't worry it's only an experiment - which will do what we imagined in the previous paragraph:
#!/usr/bin/env sh
set -eu
# Install bump-cli (published as a Ruby gem)
gem install bump-cli
# For each file from the available `*.json` files
for api in spec/json/*.json; do
# Extract the API name from filename `twilio_<api_name>_vN.json`
apiName="${api%_*}" # remove everything after the last '_'
apiName="${apiName#*_}" # remove everything before the first '_'
# Auto-create documentation <apiName> from the api definition file
# in the 'twilio' hub
bump deploy \
--doc "${apiName}" --token "${BUMP_TOKEN}" \
--hub twilio --auto-create \
"${api}"
done
The bump deploy command is where all the magic happens: it will push the api definition file to generate its documentation on Bump. By passing the --auto-create flag together with the --hub twilio and --doc ${apiName} flags we are going to create a documentation called ${apiName} if it doesn't exist. On all future changes of the definition files, it will simply be updated.
And now the Github Action workflow to use the script above on each commit of the main branch of our git repository:
name: Deploy twilio API documentations on Bump
on:
push:
branches:
- main
jobs:
deploy-doc:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- uses: ruby/setup-ruby@v1
with:
ruby-version: 2.7
bundler-cache: true
- run: sh ./.github/scripts/deploy-all.sh
env:
BUMP_TOKEN: ${{ secrets.BUMP_TOKEN }}
We are almost there! You might notice we are using a secrets.BUMP_TOKEN variable which needs to be added in the settings of my Github repository. Let's get our hub access token from Bump.
Creating the Twilio hub page on Bump.sh
OK let's leave the terminal and head to my Bump.sh account in order to create the hub. I'm headed to bump.sh/hubs/new to do so.
Now my hub is created, I can retrieve my hub token from my hub Settings > CI deployment page
And adding the token to my Github repository secrets at the following location: https://github.com/paulRbr/twilio-oai/settings/secrets/actions (Don't forget to change your project namespace in the URL if you're trying it out)
We are now ready to push our two files - the sh script and the Github Action workflow - of the previous paragraph.
Shall we try to git push origin main?
The screenshot above shows the Github Action logs that ran successfully on my main branch after pushing. We can see everything seems to have worked as expected.
Refining the resulting Twilio API reference hub
It's live! https://bump.sh/hub/twilio/ ?
The result is already pretty nice. We can browse each API documentation and have a good overview of what Twilio's API can offer. Let's see what we can change on Bump and in Twilio's definition files to make it even better.
Grouping by categories and UI customisation
Here are some of the configuration option I changed in my hub settings page:
- Select the grouping mode of API docs to “by category” from the hub
Settings > Customize UIpage - Adding a category to each documentation from their respective
Settings > Hubs settingspage- Moving the main
apidocumentation into a dedicated category called “Main” - Moving all docs containing the word
TODO:into a dedicated “Todo” category (Might be useful for the Twilio dev team to track which api definition files needs attention) - Moving all tools related docs into a category “Tools”
- All the other docs will land in a category that I named “Uncategorized”
- Moving the main
- Changing the hub defaults from the
Default settingspage, which will apply to all documentations of that hub- Uploading Twilio's logo
- Change the color scheme to red
- Change default navigation to
Groups and operations with verbsto display all API operations with their associated HTTP verb in the navigation bar of each documentation page
Updating the api definition files
Now the hub is looking all good. We can get back to API definitions in our favorite text editor.
To demonstrate the automatic documentation updates I have commited some changes on all API *.json files. The goal was to change their description fields and mark all docs as “unofficial” to not confuse end-users.
After 1min our Github Action workflow reports a successful run. Meaning our hub and all subsequent documenation pages have been updated.
That's about it. If you have a set of different APIs and need a centralised public page for your docs Bump can help you out. Give it a try and let us know what you think or how we can improve to better fit your needs.
Have fun, stay free and stay kind.
✨
This content originally appeared on DEV Community and was authored by Paul B.
Paul B. | Sciencx (2021-04-22T12:46:47+00:00) Playing with Twilio’s OpenAPI specifications. Retrieved from https://www.scien.cx/2021/04/22/playing-with-twilios-openapi-specifications/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.