Readyapi CLI

Command-line interface to work with OpenAPI files

Features

• Format & validate OpenAPI files
• Upload your OpenAPI files to Readyapi
• Get a fully mocked API for testing purposes
• Preview your API reference
• Bundle multiple OpenAPI files

Quickstart

npx @readyapi/cli help

Installation

If you really want to become friends you should install the CLI:

npm -g install @readyapi/cli

Otherwise just prefix all commands with npx @readyapi/cli instead of readyapi. That’s fine, too.

Commands

format

The given JSON file will be formatted with Prettier.

readyapi format
readyapi format openapi.json --output openapi.yaml
readyapi format https://example.com/openapi.json --output openapi.json

validate

To check whether your OpenAPI file adheres to the Swagger 2.0, OpenAPI 3.0 or OpenAPI 3.1 specification, run the following command:

readyapi validate
readyapi validate openapi.json
readyapi validate https://example.com/openapi.json

share

To quickly share an OpenAPI file or reference with someone, you can use the share command:

readyapi share
readyapi share openapi.json

This will upload your OpenAPI file to the Readyapi Sandbox to give you a public reference URL and a public URL to your OpenAPI JSON file.

reference

You can quickly spin up a local server with an API reference based on your OpenAPI file.

readyapi reference
readyapi reference openapi.json
readyapi reference openapi.json --port 1234
readyapi reference openapi.json --watch
readyapi reference https://example.com/openapi.json --watch

mock

We can even mock your API, and it’s just one command:

readyapi mock

This will boot up a server on port 3000 which gives you an API returning the dummy data according to your schema.

If you’d like to watch for file changes (to the OpenAPI file), do it like this:

readyapi mock openapi.json --watch

You can also change the port like this:

readyapi mock openapi.json --watch --port 8080

And it even works with URLs:

readyapi mock https://example.com/openapi.json --watch

bundle

Warning! The bundle command isn’t ready for production yet. Circular dependencies are not supported yet.

Some OpenAPI files reference other files from the file system or an URL. You can bundle those files and make them a single file:

readyapi bundle openapi.json --output bundle.json

If you don’t provide an output file name, the input file will be overwritten.

init

If you’re tired of passing the file name again and again, just configure it once:

readyapi init

This will create a readyapi.config.json file for you. All commands will use the configured OpenAPI file by default.

Options

--version

If you want to check which version of the CLI is installed, just run this:

readyapi --version

--help

readyapi --help

GitHub Actions

To validate your OpenAPI file in GitHub Actions, add this workflow:

# .github/workflows/validate-openapi-file.yml
name: Validate OpenAPI File

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Validate OpenAPI File
        # Replace `./my-openapi-file.json` with the correct path and filename for your project.
        # Or: run `npx @readyapi/cli init` and add the config file to your repository.
        run: npx @readyapi/cli validate ./my-openapi-file.json

Development

Set up the development environment:

pnpm install
pnpm @readyapi/cli --version

To symlink the package and use it globally on your machine:

pnpm cli:link
readyapi --version