GitHub Actions Example: Syncing OpenAPI

🚧

Deprecated Guidance

This example is only applicable for projects that are still on our legacy project architecture and have not yet migrated to ReadMe Refactored. The legacy project architecture requires rdme@9. You can find more info in our rdme migration guide or by reaching out to us at [email protected].

We will be updating this document with our latest guidance soon. Thanks for your patience!

Is your OpenAPI definition stored on GitHub? With the rdme GitHub Action, you can sync it to ReadMe every time it's updated in GitHub. Let's go over how to set this up!

"Automagical" Workflow File Generation

To set up a GitHub Actions workflow for syncing an OpenAPI or Swagger definition, the fastest and easiest way to do so is by running the following command on your local machine:

rdme openapi --github

This will locate your OpenAPI definition, sync it to ReadMe, and then create your GitHub Actions workflow file. Once that's done, create your repository secret, push your workflow file to GitHub, and get syncing! 🎊

Constructing a GitHub Actions Workflow File By Hand

🚧

Wait — there’s an easier way to do this!

The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps detailed above. The rdme CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing.

In order to construct the file by hand, you'll first want to obtain a unique API definition ID from ReadMe so we know which definition you want to update on subsequent re-syncs. You can obtain this API definition ID in one of several ways, but we'll dive into two below: uploading a file directly into the ReadMe dashboard and using the rdme CLI locally.

rdme openapi [url-or-local-path-to-file]

You've successfully updated an OpenAPI file on your ReadMe project!

        http://dash.readme.com/project/{your_project}/v1.0/refs/pet

To update your OpenAPI definition, run the following:

        rdme openapi [url-or-local-path-to-file] --key=<key> --id=API_DEFINITION_ID

We have a walkthrough video available which goes over the whole end-to-end process of obtaining the API definition ID and constructing the GitHub Actions workflow file.

You can find the video here: https://www.loom.com/share/e32c20a9dc2f4eeeab42d0c18ba24478.

Once you've obtained your API definition ID (let's call it API_DEFINITION_ID), your full GitHub Workflow file will look something like this:

name: Sync OpenAPI definition to ReadMe

# Run workflow for every push to the `main` branch
on:
  push:
    branches:
      - main

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout this repo
        uses: actions/checkout@v4

      # Run GitHub Action to sync OpenAPI file at ./path-to-file.json
      - name: GitHub Action
        # We recommend specifying a fixed version, i.e. @v10
        # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
        uses: readmeio/rdme@v10
        with:
          rdme: openapi ./path-to-file.json --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID

In the example above, every push to the main branch will sync the OpenAPI file located at ./path-to-file.json to the API specification API_DEFINITION_ID in your ReadMe project.

📘

Keeping rdme up-to-date

Note that @v10 (used in the above example) is the latest version of rdme. We recommend configuring Dependabot to keep your actions up-to-date.