# Rate My OpenAPI > Complete documentation for Large Language Models --- ## Document: GitHub Action URL: /github-action # 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](https://docs.ratemyopenapi.com/pricing) (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`). :::warning{title="New API keys required"} On May 12, 2026, Rate My OpenAPI switched to a new registration system. API keys created before that date no longer work. Subscribing again issues a new key automatically. ::: ### Basic setup Lint an OpenAPI definition file using the default configuration: ```yaml 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: ```yaml 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** ```yaml - 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. ```yaml 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 }} ``` :::warning{title="Reports are public"} All reports generated by Rate My OpenAPI are public (with an unguessable UUID URL), even when uploaded with an API key. Anyone with the URL to your report can access it. ::: Source code and documentation at [zuplo/rmoa-action](https://github.com/zuplo/rmoa-action). --- ## Document: CLI URL: /cli # CLI The CLI is perfect for developers who prefer the command line or need to integrate quality checks into their development workflow. It returns the same lint results as the website. ## Running the CLI Run the CLI with `npx` — no install required, always picks up the latest version: ```bash npx rmoa lint --filename --api-key ``` Prefer a global install? You can still do that: ```bash npm install -g rmoa rmoa lint --filename --api-key ``` The rest of this page uses `npx rmoa`. Drop the `npx` if you've installed globally. ## Usage Use the CLI to lint and get a score for your OpenAPI definition in a format that's easy to parse and integrate with your development workflow. ### Getting an API key The CLI calls the Rate My OpenAPI API, which requires an API key. [Subscribe to the free plan](https://docs.ratemyopenapi.com/pricing) (free forever) to register or log in — your API key is created automatically and is available in your dashboard. :::warning{title="New API keys required"} On May 12, 2026, Rate My OpenAPI switched to a new registration system. API keys created before that date no longer work. Subscribing again issues a new key automatically. ::: ### Basic Lint an OpenAPI definition in JSON or YAML format using the CLI's default configuration: ```bash npx rmoa lint --filename --api-key ``` ### Advanced Override the minimum passing score (default 80 / 100), cap the allowed warnings and errors, and switch the output to JSON: ```bash npx rmoa lint \ --filename \ --api-key \ --minimum-score 60 \ --max-warnings 10 \ --max-errors 0 \ --output json ``` ### Sample output ```text Rate OpenAPI file openapi.json Press Ctrl+C to cancel. ✔ Loading file for processing ✔ Analyzing file ==> Results Overall 51 ====== - Docs 56 - Completeness 53 - SDK Generation 72 - Security 35 ====== View details of your report at https://ratemyopenapi.com/report/c6cb55f4-143d-48ed-88d9-aa7a6a6585bb ``` :::warning{title="Reports are public"} All reports generated by Rate My OpenAPI are public (with an unguessable UUID URL), even when uploaded with an API key. Anyone with the URL to your report can access it. ::: ### Commands ```bash npx rmoa Commands: npx rmoa lint Lint and get a score for your OpenAPI definition using the Rate My OpenAPI ruleset Options: --version Show version number [boolean] --help Show help [boolean] --api-key Your Rate My OpenAPI API Key [string] [required] --filename The OpenAPI file name to process [string] [required] --dir The directory containing your OpenAPI file [string] [default: "."] --output default, json [string] [default: "default"] --max-warnings The maximum number of warnings allowed before labeling the ru n as failed. [number] --max-errors The maximum number of errors allowed before labeling the run as failed. [number] --minimum-score The minimum score (0 - 100) to label a lint run as successful /passing. Default is 80. [number] [default: 80] ``` Source code and documentation at [zuplo/rate-my-openapi](https://github.com/zuplo/rate-my-openapi). --- ## Document: Introduction URL: / # Introduction At Zuplo we believe that the better the quality of an OpenAPI document, the better the developer experience will be for the consumers of that API. This experience is important for the success of an API. Rate My OpenAPI is a suite of tools designed to help software developers using OpenAPI to meet high standards of quality and usability when designing and developing their APIs. Our tools include a website, a CLI, a GitHub Action and an API, all aimed at ensuring your APIs meet high standards of quality and usability. :::warning{title="New API keys required"} On May 12, 2026, Rate My OpenAPI switched to a new registration system. API keys created before that date no longer work. [Subscribe to the free plan](https://docs.ratemyopenapi.com/pricing) (free forever) to register or log in — a new key is created for you automatically. ::: ## Quickstart 1. [Subscribe to the free plan](https://docs.ratemyopenapi.com/pricing) (free forever) to register or log in. Your API key is created automatically. 2. Copy your API key from the dashboard. 3. Lint your OpenAPI file using the [CLI](./cli) or the [GitHub Action](./github-action). ## Categories of evaluation Our tools evaluate your OpenAPI definition files and provide a comprehensive score based on four key categories: - **Documentation:** Ensure your API is well-documented, making it easy for users to understand and use. - **SDK Generation:** Verify that your API definition supports SDK generation, facilitating integration and usage in different programming languages. - **Security:** Check for best practices and standards to ensure your API is secure and protected against common vulnerabilities. - **Completeness:** Ensure your API definition is complete, with all necessary endpoints, parameters, and responses accurately defined. ## Tools ### Website [https://ratemyopenapi.com](https://ratemyopenapi.com) offers a user-friendly interface for developers to upload and analyze their OpenAPI definition files. Key features include: - **Linting:** Upload and lint your OpenAPI files to receive detailed feedback. - **Comprehensive scoring:** Get a clear, actionable score rating your API's documentation, SDK generation, security, and completeness. - **Detailed reports:** Access in-depth reports that highlight areas of improvement and provide recommendations. - **Visualization:** Easily visualize the structure and quality of your API with in-line feedback. ### CLI The CLI is perfect for developers who prefer the command line or need to integrate quality checks into their development workflow. Run it instantly with `npx rmoa` — no install required: ```bash npx rmoa lint --filename --api-key ``` Key features include: - **Zero install:** Run via `npx rmoa` to always pick up the latest version. - **Automated checks:** Integrate the CLI into your CI/CD pipeline for automated quality checks on every commit. - **Detailed output:** Get detailed feedback directly in your terminal, with options to further integrate these results into your development flow. See the [CLI page](./cli) for full usage. ### GitHub Action Our GitHub Action seamlessly integrates with your repository to ensure your APIs are consistently of high quality. Key features include: - **Automated linting:** Automatically lint OpenAPI definition files on every pull request and push to ensure code quality. - **Inline feedback:** Receive feedback directly in your pull requests with comments highlighting issues and areas for improvement. - **Continuous improvement:** Maintain a high standard of API quality with continuous monitoring and feedback.