GitHub Actions Example: Syncing OpenAPI
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.
Uploading a file
Follow these instructions on uploading a new OpenAPI file in the dashboard. Once the file is uploaded, you'll see the following in the API Reference settings of your dashboard (the red outline is where you'll find your API definition ID):
Using the rdme
CLI
Alternatively, you can obtain the API definition ID by running the following rdme
CLI command on your local machine:
rdme openapi [url-or-local-path-to-file]
Once you follow the prompts and upload your OpenAPI definition, you'll receive a confirmation message that looks something like this:
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:
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. @v8
# Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
uses: readmeio/rdme@v8
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-dateNote that
@v8
(used in the above example) is the latest version ofrdme
. We recommend configuring Dependabot to keep your actions up-to-date.
Updated 3 months ago