Automate Docs as Code via GitHub Actions

The entire docs as code process can be automated via GitHub Actions, enabling any changes made to the documentation to be deployed instantly.

note

Take a look at the GitHub repository for a sample automated workflow.

In this case, whenever a change is pushed to the GitHub repository, the contents of the repository are zipped and sent to the Portal Generation Endpoint. The response received from this endpoint contains the Portal artifacts that are unzipped and deployed to the server.

1. Click Fork in the top-right corner to fork the sample GitHub repo. Select an Owner and provide the Repository name. By default, forks are named the same as their parent repositories. Optionally add a Description and click Create Fork.

   

The forked repository contains a sample workflow file, DeployStaticPortal.yml, in the .github/workflows directory. This contains the steps to build the API Portal from the GitHub repo contents.

2. Add steps in the workflow file to generate the API Portal using the APIMatic API and deploy it to Netlify.

note

You can deploy to other platforms such as Cloudflare Pages or Azure Static Web Apps.

The sample workflow file, DeployStaticPortal.yml, contains the following steps:

• Check out the repository
• Zip the contents of the repository
• Call APIMatic’s Portal Generation API
• Download and unzip the response received from the APIMatic API
• Deploy the generated Portal to Netlify

name: Deploy Static Portal

on:
  workflow_dispatch:  
  push:
    branches: 
      - master 
      
jobs:
  generate-portal:
    runs-on: ubuntu-latest

    steps:
       
    - uses: actions/checkout@v1
      name : checkout-repo
      id: checkout-repo  
      
    - name: Zip files
      run: zip -qq -r portal-input.zip .
      
    - name: Call build endpoint
      run: curl -X POST --url 'https://www.apimatic.io/api/portal' -H 'Authorization:X-Auth-Key ${{ secrets.API_KEY }}' -F 'file=@portal-input.zip' -o portal-output.zip
      
    - name: Extract generated Portal
      run: unzip -qq portal-output.zip -d static-portal
    
    - name: Deploy to Netlify
          uses: nwtgck/actions-netlify@v1.2
          with:
            publish-dir: './static-portal'
            production-branch: master
            github-token: ${{ secrets.GITHUB_TOKEN }}
            deploy-message: "Deploy from GitHub Actions"
            enable-pull-request-comment: false
            enable-commit-comment: true
            overwrites-pull-request-comment: true
          env:
            NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
            NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
          timeout-minutes: 1  

3. The forked repository does not copy the secrets maintained in the parent repository. Therefore, you have to create secrets again. Go to your GitHub repo and choose the Settings tab. Click Secrets > Actions on the left, and then choose New repository secret on the right panel.

   

4. The GitHub Action will trigger when any commit is pushed to the master branch of your repository. Alternatively, you can also trigger the workflow manually. As soon as the workflow run completes, you should be able to view the updated Portal on the deployed server.