Use our APITree Github Action
to automatically upload your APIs to APITree as part of your CI/CD workflow.
GitHub Action
is a fast, secure, and easy solution to have an up-to-date API documentation.
On this page we explain you how to integrate the Action.
How to use the GitHub Action
Integration Guide
In order to use the GitHub Action you need an APITree and a GitHub account containing
a public or private GitHub repository, an OpenAPI v2 or v3 file somewhere in your
repository, and a GitHub workflow file.
Go to the APITree GitHub Action on the GitHub Marketplace
and read the instructions how to use it and to learn more about the available options.
It is recommended to always use the latest version of the Action.
The first step is to create a new workflow file or to extend an existing one.
In this example we create a new file .github/workflows/workflow.yaml.
The workflow will sync the API on every push event on the master
branch. The workflow executes the job publish-api-doc. This job
checks out the repository and uploads the API file openapi.yaml
to APITree.
There are a couple of environment variables needed. Continue reading to find
out where to get the values from.
name: APITree
on:
push:
branches:
- master
jobs:
publish-api-doc:
name: Publish API documentation on APITree
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Upload API
uses: apitree/github-actions@master
env:
apitree_user_id: <APITREE_USER_ID>
apitree_api_nickname: <APITREE_API_NICKNAME>
apitree_api_file: openapi.yaml
apitree_token: ${{ secrets.APITREE_TOKEN }}
Note: The APITree GitHub Action makes use of the REST API from APITree. Using the REST API
allows you to easily set up an API sync for other CI tools such as Jenkins or Circle CI as well.
workflow.yaml replacements
<APITREE_USER_ID>
Login to your account. In the left sidebar click Profile.
Go to your workflow file and replace <APITREE_USER_ID> with your Account ID.
workflow.yaml replacements
<APITREE_API_NICKNAME>
Go to your workflow file and replace <APITREE_API_NICKNAME> with a
nickname for the API of your choice. Allowed characters are: A-Z, a-z, 0-9, -, _.
workflow.yaml replacements
<APITREE_TOKEN>
Login to your account. In the left sidebar click API Tokens.
Click the Create Token button.
Enter a name like GitHub Action, select the OAuth scope
api, and click on Create.
You will get the API token displayed once. Treat the API token like a password
and store it in a safe place.
Navigate to your GitHub repository you want to set up the GitHub Action for.
Click on the tab Settings, in the left sidebar click
Secrets. Click on Add a new secret.
Create a new secret named API_TOKEN and use the APITree API token
as value. Click on Add secret.
The secret is now ready to use in the GitHub workflow.
Final Step
Run the action
The final step is to run the Action. Push some changes to your repository. The GitHub
Action will automatically start running. Go to your repository and click on the tab
Actions. You should see a successful workflow run like this:
