stats

Introduction

The stats command provides statistics about the structure of one or more API description files. This command generates statistics for the following metrics:

• References
• External Documents
• Schemas
• Parameters
• Links
• Path Items
• Operations
• Tags

If you're interested in the technical details, the statistics are calculated using the counting logic from the StatsVisitor module.

Usage

redocly stats <api>
redocly stats <api> [--format=<option>] [--config=<path>]
redocly stats --version

Options

Examples

Specify API

The stats command behaves differently depending on how you pass the API to it, and whether the configuration file exists.

Pass an API directly

You can use the stats command with an OpenAPI description directly, with a command like the following:

redocly stats openapi/openapi.yaml

In this case, stats shows statistics for the API description that was passed in.

Pass an API alias

Instead of a full path, you can use an API name from the apis section of your Redocly configuration file. For example, with a redocly.yaml configuration file containing the following entry for core@v1:

apis:
  core@v1:
    root: ./openapi/api-description.json

You can obtain the statistics by giving the API alias name, as shown below:

redocly stats core@v1

In this case, after resolving the path behind the core@v1 name, stats displays statistics for the openapi/api-description.json file. For this approach, the Redocly configuration file is mandatory.

Use alternative configuration file

By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional --config argument to provide an alternative path to a configuration file.

redocly stats --config=./another/directory/config.yaml

Specify output format

Specify the stylish (default) output format

The default output format for stats is called "stylish". It outputs a nice format for your terminal, as shown in the following example:

Document: museum.yaml stats:

🚗 References: 35
📦 External Documents: 0
📈 Schemas: 23
👉 Parameters: 6
🔗 Links: 0
🔀 Path Items: 5
👷 Operations: 8
🔖 Tags: 3

museum.yaml: stats processed in 4ms

In this format, stats shows the statistics in a condensed but readable manner with an icon at the beginning of each line.

Specify the JSON output format

Use --format=json to get a machine-readable output format. The JSON format output is shown in the following example:

{
  "refs": {
    "metric": "🚗 References",
    "total": 35
  },
  "externalDocs": {
    "metric": "📦 External Documents",
    "total": 0
  },
  "schemas": {
    "metric": "📈 Schemas",
    "total": 23
  },
  "parameters": {
    "metric": "👉 Parameters",
    "total": 6
  },
  "links": {
    "metric": "🔗 Links",
    "total": 0
  },
  "pathItems": {
    "metric": "🔀 Path Items",
    "total": 5
  },
  "operations": {
    "metric": "👷 Operations",
    "total": 8
  },
  "tags": {
    "metric": "🔖 Tags",
    "total": 3
  }
}

The JSON format output is suitable when you want to use the stats data in another program.

Specify the Markdown output format

Use --format=markdown to return output that you can use in Markdown files or other Markdown-friendly applications. A table format is used.

The following is an example source output:

| Feature  | Count  |
| --- | --- |
| 🚗 References | 35 |
| 📦 External Documents | 0 |
| 📈 Schemas | 23 |
| 👉 Parameters | 6 |
| 🔗 Links | 0 |
| 🔀 Path Items | 5 |
| 👷 Operations | 8 |
| 🔖 Tags | 3 |

Here's the rendered example source output:

The Markdown format is suitable when a printable summary is needed, such as for regularly updated reports or human-readable output from your CI system.

The following example shows how to use the stats command in a GitHub action to make a GitHub summary:

name: Get API stats
on: push

jobs:
  get_stats:
    name: Stats as a job summary
    runs-on: ubuntu-latest
    steps:
      - name: Check out repo's default branch
        uses: actions/checkout@v4
      - name: Set up node
        uses: actions/setup-node@v4
      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest
      - name: Get stats
        run: redocly stats --format=markdown museum.yaml >> $GITHUB_STEP_SUMMARY 2>&1

This GitHub action uses the output of the stats command in Markdown format as the input value for $GITHUB_STEP_SUMMARY. When the job is complete, your API stats are added to the summary page, as shown in the following screenshot: