OpenAPI + GitHub Sync

With GitHub Actions, it's super easy to automatically sync your OpenAPI document whenever changes occur in your GitHub repo!

πŸ‘

Check out the API Reference section of your Project Dashboard!

While the YAML snippet on this page is a generic template that you'll need to make some adjustments to, you'll find a personalized onboarding experience in your Project Dashboard with a YAML snippet that you can copy and paste β€” no adjustments needed! Check out the API Reference section of your project dashboard and click the big blue Add your first API (or Add more endpoints, if you've added an API already) button.

Just create a new file in your GitHub repository called .github/workflows/readme-github-sync.yml and populate it with the template below. You only fill in one parameter from the ReadMe Dashboard and you'll be good to go!

Any subsequent commits to the main or master branch (whichever is your default branchβ€”you can also specify any GitHub event of your choiceβ€”see GitHub's docs for more info) will automatically trigger the sync process and upload your specified OpenAPI file to ReadMe.

name: Sync OAS to ReadMe
on:
  push:
    branches:
      - main
      - master
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
      - uses: readmeio/[email protected]
        with:
          readme-oas-key: 'unique-key-from-dashboard'
           
          # OPTIONAL CONFIG, use if necessary
          # oas-file-path: './swagger.json'
          # api-version: 'v1.0.0'

🚧

Public Repo? Secretly store your ReadMe API Key!

GitHub Actions have a way to securely store sensitive information (such as your ReadMe API Key and API Specification ID), so it isn't publicly visible. You can read more in their documentation.

Parameter

Description

readme-oas-key

Required This value can be obtained from the project dashboard when adding a new API to your project. For migrating existing APIs, see here.

oas-file-path

Optional Path to OpenAPI document that will be synced to ReadMe. By default, we try to find the spec file in the directory automatically (i.e. if it's a JSON or YAML file with filenames like swagger, oas, or openapi).

api-version

Optional Existing ReadMe Version to upload to. By default, we use the version specified in the spec file.

More info: Versions in ReadMe and specifying the version in the OpenAPI Info object

Migrating Existing APIs to GitHub Sync

If you want to migrate APIs that are already synced into ReadMe via another mechanism, it's super easy! The value for readme-oas-key is your ReadMe Project API Key and the API Specification ID (pictured below) separated by a colon (i.e. apiKey:apiSpecId).

Use readme-oas-key in your .github/workflows/readme-github-sync.yml file and any subsequent pushes to the master branch (or whichever branch(es) you specify in your workflow file) in that GitHub repository will sync that OpenAPI file to ReadMe!

πŸ“˜

Keeping Your GitHub Action Up-to-Date

To ensure that you're on the latest version of our GitHub Action (along with all of your project dependencies), we highly recommend setting up Dependabot, which automatically updates your project dependencies (including this one!). As a fallback, we recommend keeping your version of the github-readme-sync package set to v2 as denoted above, which ensures that your workflow will execute the latest available version within the version 2 range.

Troubleshooting

If you're seeing failures with the GitHub Action and need to troubleshoot the issue, we provide comprehensive step-by-step debug logs. We may ask for these logs (as well as a copy of your API specification file) when you contact our support team. You can enable Step Debug Logs in your GitHub Actions workflow by setting the repository secret ACTIONS_STEP_DEBUG to true. For more information on accessing, downloading, and deleting logs, check out GitHub's documentation.

🚧

Debug Logs May Contain Sensitive Information

Enabling Step Debug Logs will produce comprehensive logging for all of your GitHub Action workflows. While we sanitize all logging output to prevent API keys from being visible, the logs may contain other sensitive information (from ReadMe and any other services that you use). Anybody with read access to the repository will be able to see these logs.

We strongly recommend that you only enable this setting in private repositories. If working in a public repository, we suggest creating a separate private repository with your GitHub workflow and OpenAPI/Swagger files before enabling this debugger.

If you do enable Step Debug Logs in your repository and your logs produce sensitive information, here are GitHub's docs on deleting logs.

Example

Want to see the GitHub Action in action? Check out this example repository: kanadgupta/metrotransit-nextrip-oas

To see an example where multiple OpenAPI/Swagger files are synced in the same repository, check out jesseyowell/oas-test-files.


Did this page help you?