mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-09 12:47:48 +00:00
sync: Synced local 'docs/' with remote 'docs/cli/'
This commit is contained in:
redocly-bot
@@ -1,122 +1,142 @@
|
|||||||
# `stats`
|
# `stats`
|
||||||
|
|
||||||
The `stats` command provides statistics about the structure of one or more API definition files. Statistics are calculated using the counting logic from the `StatsVisitor` module. The `stats` command can generate statistics for the following:
|
## Introduction
|
||||||
|
|
||||||
|
The `stats` command provides statistics about the structure of one or more API definition files. Statistics are calculated using the counting logic from the `StatsVisitor` module. The `stats` command can generate statistics for the following metrics:
|
||||||
|
|
||||||
```shell
|
* `References`
|
||||||
Metrics:
|
* `External Documents`
|
||||||
References,
|
* `Schemas`
|
||||||
External Documents,
|
* `Parameters`
|
||||||
Schemas,
|
* `Links`
|
||||||
Parameters,
|
* `Path Items`
|
||||||
Links,
|
* `Operations`
|
||||||
Path Items,
|
* `Tags`
|
||||||
Operations,
|
|
||||||
Tags
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
### `stats` usage
|
|
||||||
|
|
||||||
|
|
||||||
```shell
|
|
||||||
Positionals:
|
|
||||||
entrypoint [string] [required]
|
|
||||||
Options:
|
|
||||||
--version Show version number. [boolean]
|
|
||||||
--help Show help. [boolean]
|
|
||||||
--format Use a specific output format.
|
|
||||||
[choices: "stylish", "json"] [default: "stylish"]
|
|
||||||
--config Specify path to the config file. [string]
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
The command:
|
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openapi stats openapi/petstore.yaml
|
openapi stats <entrypoint>
|
||||||
|
openapi stats <entrypoint> [--format] [--config=<path>]
|
||||||
|
openapi stats --version
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Options
|
||||||
|
|
||||||
The output will be:
|
Option | Type | Required | Default | Description
|
||||||
|
--------------------------|:---------:|:------------:|:-----------:|------------
|
||||||
|
`entrypoint` | `string` | yes | - | Path to the API definition filename that you want to calculate statistics for. Instead of full paths, you can use aliases assigned in the `apiDefinitions` section within your `.redocly.yaml` configuration file as entrypoints. Refer to [the entrypoint section below](#entrypoint) for more options.
|
||||||
|
`--config` | `string` | no | - | Specify path to the [config file](#custom-configuration-file)
|
||||||
|
`--format` | `string` | no | `stylish` | Format for the output.<br />**Possible values:** `stylish`, `json`
|
||||||
|
`--help` | `boolean` | no | - | Show help
|
||||||
|
`--version` | `boolean` | no | - | Show version number
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
```shell
|
### Entrypoint
|
||||||
🚗 References: 12
|
|
||||||
📦 External Documents: 3
|
|
||||||
📈 Schemas: 10
|
|
||||||
👉 Parameters: 9
|
|
||||||
🔗 Links: 0
|
|
||||||
➡️ Path Items: 16
|
|
||||||
👷 Operations: 22
|
|
||||||
🔖 Tags: 5
|
|
||||||
```
|
|
||||||
|
|
||||||
|
The `stats` command behaves differently depending on how you pass the entrypoint to it and whether the [configuration file](#custom-configuration-file) exists.
|
||||||
|
|
||||||
### Options
|
#### Pass entrypoint directly
|
||||||
|
|
||||||
#### Format
|
|
||||||
|
|
||||||
The `stats` command supports two output formats: `stylish` and `json`. Choose which format to use with the optional `--format` argument.
|
|
||||||
|
|
||||||
The default format is `stylish`, with colored text and an icon at the beginning of each line.
|
|
||||||
|
|
||||||
|
|
||||||
**Example JSON output**
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openapi stats test.yaml --format=json
|
openapi stats openapi/openapi.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
|
In this case, `stats` will show statistics for the definition that was passed to the command. The configuration file is ignored.
|
||||||
|
|
||||||
```json
|
#### Pass entrypoint via configuration file
|
||||||
Document: test.yaml stats:
|
|
||||||
|
|
||||||
{
|
Instead of full paths, you can use aliases assigned in your `apiDefinitions` within your `.redocly.yaml` configuration file as entrypoints.
|
||||||
"refs": {
|
|
||||||
"metric": "🚗 References",
|
```bash command
|
||||||
"total": 1
|
openapi stats petstore
|
||||||
},
|
```
|
||||||
"externalDocs": {
|
|
||||||
"metric": "📦 External Documents",
|
```yaml .redocly.yaml
|
||||||
"total": 0
|
apiDefinitions:
|
||||||
},
|
petstore: ./openapi/petstore-definition.json
|
||||||
"schemas": {
|
```
|
||||||
"metric": "📈 Schemas",
|
|
||||||
"total": 1
|
In this case, after resolving the path behind the `petstore` alias (see the `.redocly.yaml` tab), `stats` will show statistics for the `petstore.json` definition file. The presence of the `.redocly.yaml` configuration file is mandatory.
|
||||||
},
|
|
||||||
"parameters": {
|
### Custom configuration file
|
||||||
"metric": "👉 Parameters",
|
|
||||||
"total": 2
|
By default, the CLI tool looks for a `.redocly.yaml` configuration file in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
|
||||||
},
|
|
||||||
"links": {
|
```bash
|
||||||
"metric": "🔗 Links",
|
openapi stats --config=./another/directory/config.yaml
|
||||||
"total": 0
|
```
|
||||||
},
|
|
||||||
"pathItems": {
|
### Format
|
||||||
"metric": "➡️ Path Items",
|
|
||||||
"total": 3
|
#### Stylish (default)
|
||||||
},
|
|
||||||
"operations": {
|
```bash request
|
||||||
"metric": "👷 Operations",
|
openapi stats pet.yaml
|
||||||
"total": 3
|
```
|
||||||
},
|
|
||||||
"tags": {
|
```bash output
|
||||||
"metric": "🔖 Tags",
|
Document: pet.yaml stats:
|
||||||
"total": 2
|
|
||||||
}
|
🚗 References: 3
|
||||||
|
📦 External Documents: 0
|
||||||
|
📈 Schemas: 3
|
||||||
|
👉 Parameters: 2
|
||||||
|
🔗 Links: 0
|
||||||
|
➡️ Path Items: 2
|
||||||
|
👷 Operations: 3
|
||||||
|
🔖 Tags: 1
|
||||||
|
|
||||||
|
pet.yaml: stats processed in 6ms
|
||||||
|
```
|
||||||
|
|
||||||
|
In this format, `stats` shows the statistics for the metrics mentioned in the [Introduction section](#introduction) in condensed output with colored text and an icon at the beginning of each line.
|
||||||
|
|
||||||
|
#### JSON
|
||||||
|
|
||||||
|
```bash request
|
||||||
|
openapi stats pet.yaml --format=json
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash output
|
||||||
|
Document: pet.yaml stats:
|
||||||
|
|
||||||
|
{
|
||||||
|
"refs": {
|
||||||
|
"metric": "🚗 References",
|
||||||
|
"total": 3
|
||||||
|
},
|
||||||
|
"externalDocs": {
|
||||||
|
"metric": "📦 External Documents",
|
||||||
|
"total": 0
|
||||||
|
},
|
||||||
|
"schemas": {
|
||||||
|
"metric": "📈 Schemas",
|
||||||
|
"total": 3
|
||||||
|
},
|
||||||
|
"parameters": {
|
||||||
|
"metric": "👉 Parameters",
|
||||||
|
"total": 2
|
||||||
|
},
|
||||||
|
"links": {
|
||||||
|
"metric": "🔗 Links",
|
||||||
|
"total": 0
|
||||||
|
},
|
||||||
|
"pathItems": {
|
||||||
|
"metric": "➡️ Path Items",
|
||||||
|
"total": 2
|
||||||
|
},
|
||||||
|
"operations": {
|
||||||
|
"metric": "👷 Operations",
|
||||||
|
"total": 3
|
||||||
|
},
|
||||||
|
"tags": {
|
||||||
|
"metric": "🔖 Tags",
|
||||||
|
"total": 1
|
||||||
}
|
}
|
||||||
|
}
|
||||||
|
pet.yaml: stats processed in 6ms
|
||||||
```
|
```
|
||||||
|
|
||||||
|
In this format, `stats` shows the statistics for the metrics mentioned in the [Introduction section](#introduction) in JSON-like output.
|
||||||
|
|
||||||
#### Specify config file
|
|
||||||
|
|
||||||
By default, the CLI tool looks for a `.redocly.yaml` configuration file in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
|
|
||||||
|
|
||||||
|
|
||||||
```bash
|
|
||||||
openapi stats openapi/petstore.yaml --config openapi/.redocly.yaml
|
|
||||||
```
|
|
||||||
|
|||||||
Reference in New Issue
Block a user