Copy page

Documentation

GitHub Action

Our GitHub Action drops into your repository to establish best practices and continuous quality monitoring for your OpenAPI definitions.

Usage

Add the GitHub Action to your repository and configure it to run on pull requests and pushes for continuous quality monitoring.

Getting an API key

The GitHub Action calls the Rate My OpenAPI API, which requires an API key. Subscribe to the free plan (free forever) to register or log in — your API key is created automatically. Copy it from your dashboard and store it as a repository secret (e.g. RMOA_API_KEY).

Basic setup

Lint an OpenAPI definition file using the default configuration:

Code
steps:
  - uses: actions/checkout@v4
  - uses: zuplo/rmoa-action@v1
    with:
      filepath: './my-api.json'
      apikey: ${{ secrets.RMOA_API_KEY }}

Advanced setup

Override the minimum passing score (default 80 / 100) and cap the allowed warnings and errors:

Code
steps:
  - uses: actions/checkout@v4
  - uses: zuplo/rmoa-action@v1
    with:
      filepath: './my-api.json'
      apikey: ${{ secrets.RMOA_API_KEY }}
      max-errors: 0
      max-warnings: 5
      minimum-score: 70

Configuration options

Code
- uses: zuplo/rmoa-action@v1
  with:
    # File containing the OpenAPI Spec to be linted.  Examples: my-api.oas.json, api-spec.yaml
    filepath: ''

    # Your Rate My OpenAPI API key (https://docs.ratemyopenapi.com/pricing)
    apikey: ''

    # The maximum number of warnings allowed before labeling the run as failed.
    max-warnings: ''

    # The maximum number of errors allowed before labeling the run as failed.
    max-errors: ''

    # The minimum score (0 - 100) to label a lint run as successful/passing. Default is 80.
    minimum-score: ''

Example

This workflow runs rmoa-action on every pull request. The pull request cannot be merged until the OpenAPI specification in my-api.json reaches a minimum score of 80.

Code
on:
  pull_request:
    branches: [$default-branch]

jobs:
  rate-my-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: zuplo/rmoa-action@v1
        with:
          filepath: './my-api.json'
          apikey: ${{ secrets.RMOA_API_KEY }}

Source code and documentation at zuplo/rmoa-action.