Here at Bump, we want your documentation to look beautiful. That’s why we designed our layout to work with both OpenAPI and AsyncAPI specifications — just provide your API in these formats, and we’ll make it look amazing.
But where we really simplify things is the ability to update your docs automatically, so you don’t even have to think about updating. Just push your code, and we’ll make sure your docs are updated.
In this post, we’ll walk through the Bump GitHub Action. If you keep your code (with your API specification) on GitHub, this action will do the documentation updates for you. You’ll need a few things:
- A Bump.sh account.
- Your api location at Bump. You don’t actually need to upload your docs, you just need to create the location where it will reside. Once created, you’ll need a
Doc id
and anAccess token
from your docs settings. (Settings > CI deployment). - Your code (with your API document) hosted on Github.
GitHub Actions
GitHub Actions are automated tasks that GitHub will run over your repository. In this case, when a commit is made, it will take the API specification file denoted in the action (a YAML or JSON), and use it to update your documentation on Bump.
In this case, I will be updating my JokeAPI on Bump whenever new code is pushed.
Step 1: create your documentation at Bump.
In this case, I want to update my Joke API, so I’ll create a version of my API called “JokeAPI — updating from GitHub Action” You can see this version on my Bump account. I uploaded the current YAML file so that some content would be present on the site.
Inside my new API’s settings, under the “CI deployment” settings, there is a Doc id and an Access token:
We’ll need these to implement our GitHub Action. But your Access token needs to remain private, so keep it under wraps (or a salmon coloured rectangle).
Step 2: Create GitHub Action
In your GitHub repository, we’ll create our GitHub Action. Click “Actions” at the top of your repo, and then click “New Workflow”.
You’re going to get a lot of options on workflows you can create, but we can ignore these. We’ll create our workflow from scratch, so click the “set up a workflow yourself” link. (Don’t worry, you’re not doing it yourself — we’ll do it together!)
Paste in the following code:
name: Deploy documentation
on:
push:
branches:
- master
jobs:
deploy-doc:
name: Deploy API doc on Bump
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Deploy API documentation
uses: bump-sh/github-action@0.2
with:
doc: <BUMP_DOC_ID>
token: ${{secrets.BUMP_TOKEN}}
file: doc/api-documentation.yml
There are a few fields you’ll need to change:
- Branch: If your main branch is master - you're set. If you have a newer repo, your main branch is probably called main. If your branch has a different name - enter the branch you'd like to update on.
- Doc: Enter the Doc id from your Bump CI deployment settings.
- Token: Leave in this state. This is referencing a GitHub Secret. So we can use this variable to keep your Access token private.
- File: The link to your yaml/json file. In my jokes api, this became: file: joke_api_0001.yaml as my yaml is in the root directory.
GitHub Secrets
To keep your API token private, we’ll use GitHub Secrets. In your repository, click Settings: Secrets
There’s a button to create a new secret.
You can see I have created a secret called BUMP_TOKEN that holds the API token for me repo. This is referenced in the workflow using $ { { secrets.BUMP_TOKEN } }.
That’s it! Your workflow is now ready to go.
Testing out your workflow.
To test my workflow, I’ll add a fake endpoint to my API:
/fake_entry:
post:
tags:
- users
summary: fakeentry
operationId: fake
description: fake
parameters:
- in: header
name: x-admin
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
required:
- fake
- fake1
Saving this to my repo, I’ll push this code to GitHub with the commit message “adding fake params”. Immediately on the actions page, I see:
And after a few seconds: the yellow turns green, indicating that the push to Bump was successful!
Looking at the Docs
The new /fake_entry endpoint is visible under Users:
Changelog
Bump reports every change made to the API, and we can see the GitHub action report:
By clicking on the date of the item, we are directed to the diff:
Conclusion
My next edit was to remove this fake entry endpoint, so that I might continue building my Joke API:
Using the fake entry, we were able to demonstrate the power of using GitHub actions — simply updating the code in my GitHub repository resulted in the new documentation being pushed live to users.
Removing the manual step of uploading your documents ensures that whatever code is pushed to production — the docs are pushed at the same time, resulting in up-to-date documentation. Every time.
Top comments (0)