mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-07 12:47:49 +00:00
4c3d8cf84f
* docs: updated commands documentation per issue 1429 and minor corrections, ran prettier * docs: updated commands documentation per issue 1429 and included pr 1560 feedback * docs: minor formatting and copyedits --------- Co-authored-by: Diana Cheung <18452752+dianacheung@users.noreply.github.com> Co-authored-by: Lorna Mitchell <lorna.mitchell@redocly.com>
210 lines
6.7 KiB
Markdown
210 lines
6.7 KiB
Markdown
# `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
|
|
|
|
```bash
|
|
redocly stats <api>
|
|
redocly stats <api> [--format=<option>] [--config=<path>]
|
|
redocly stats --version
|
|
```
|
|
|
|
## Options
|
|
|
|
| Option | Type | Description |
|
|
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| api | string | **REQUIRED.** Path to the API description filename or alias that you want to generate the statistics for. Refer to [the API section](#specify-api) for more details. |
|
|
| --config | string | Specify path to the [configuration file](#use-alternative-configuration-file). |
|
|
| --format | string | Format for the output.<br />**Possible values:** `stylish`, `json`, `markdown`. Default value is `stylish`. |
|
|
| --help | boolean | Show help. |
|
|
| --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`. |
|
|
| --version | boolean | Show version number. |
|
|
|
|
## Examples
|
|
|
|
### Specify API
|
|
|
|
The `stats` command behaves differently depending on how you pass the API to it, and whether the [configuration file](#use-alternative-configuration-file) exists.
|
|
|
|
#### Pass an API directly
|
|
|
|
You can use the `stats` command with an OpenAPI description directly, with a command like the following:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```yaml
|
|
apis:
|
|
core@v1:
|
|
root: ./openapi/api-description.json
|
|
```
|
|
|
|
You can obtain the statistics by giving the API alias name, as shown below:
|
|
|
|
```bash
|
|
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](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
|
|
|
|
```bash
|
|
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:
|
|
|
|
<pre>
|
|
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
|
|
</pre>
|
|
|
|
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:
|
|
|
|
<pre>
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
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:
|
|
|
|
<pre>
|
|
| Feature | Count |
|
|
| --- | --- |
|
|
| 🚗 References | 35 |
|
|
| 📦 External Documents | 0 |
|
|
| 📈 Schemas | 23 |
|
|
| 👉 Parameters | 6 |
|
|
| 🔗 Links | 0 |
|
|
| 🔀 Path Items | 5 |
|
|
| 👷 Operations | 8 |
|
|
| 🔖 Tags | 3 |
|
|
|
|
</pre>
|
|
|
|
Here's the rendered example source output:
|
|
|
|
| Feature | Count |
|
|
| --------------------- | ----- |
|
|
| 🚗 References | 35 |
|
|
| 📦 External Documents | 0 |
|
|
| 📈 Schemas | 23 |
|
|
| 👉 Parameters | 6 |
|
|
| 🔗 Links | 0 |
|
|
| 🔀 Path Items | 5 |
|
|
| 👷 Operations | 8 |
|
|
| 🔖 Tags | 3 |
|
|
|
|
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](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/):
|
|
|
|
```yaml
|
|
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:
|
|
|
|
|