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`
|
||||
|
||||
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
|
||||
Metrics:
|
||||
References,
|
||||
External Documents,
|
||||
Schemas,
|
||||
Parameters,
|
||||
Links,
|
||||
Path Items,
|
||||
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:
|
||||
* `References`
|
||||
* `External Documents`
|
||||
* `Schemas`
|
||||
* `Parameters`
|
||||
* `Links`
|
||||
* `Path Items`
|
||||
* `Operations`
|
||||
* `Tags`
|
||||
|
||||
## Usage
|
||||
|
||||
```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
|
||||
🚗 References: 12
|
||||
📦 External Documents: 3
|
||||
📈 Schemas: 10
|
||||
👉 Parameters: 9
|
||||
🔗 Links: 0
|
||||
➡️ Path Items: 16
|
||||
👷 Operations: 22
|
||||
🔖 Tags: 5
|
||||
```
|
||||
### Entrypoint
|
||||
|
||||
The `stats` command behaves differently depending on how you pass the entrypoint to it and whether the [configuration file](#custom-configuration-file) exists.
|
||||
|
||||
### Options
|
||||
|
||||
#### 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**
|
||||
|
||||
#### Pass entrypoint directly
|
||||
|
||||
```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
|
||||
Document: test.yaml stats:
|
||||
#### Pass entrypoint via configuration file
|
||||
|
||||
{
|
||||
"refs": {
|
||||
"metric": "🚗 References",
|
||||
"total": 1
|
||||
},
|
||||
"externalDocs": {
|
||||
"metric": "📦 External Documents",
|
||||
"total": 0
|
||||
},
|
||||
"schemas": {
|
||||
"metric": "📈 Schemas",
|
||||
"total": 1
|
||||
},
|
||||
"parameters": {
|
||||
"metric": "👉 Parameters",
|
||||
"total": 2
|
||||
},
|
||||
"links": {
|
||||
"metric": "🔗 Links",
|
||||
"total": 0
|
||||
},
|
||||
"pathItems": {
|
||||
"metric": "➡️ Path Items",
|
||||
"total": 3
|
||||
},
|
||||
"operations": {
|
||||
"metric": "👷 Operations",
|
||||
"total": 3
|
||||
},
|
||||
"tags": {
|
||||
"metric": "🔖 Tags",
|
||||
"total": 2
|
||||
}
|
||||
}
|
||||
Instead of full paths, you can use aliases assigned in your `apiDefinitions` within your `.redocly.yaml` configuration file as entrypoints.
|
||||
|
||||
```bash command
|
||||
openapi stats petstore
|
||||
```
|
||||
|
||||
```yaml .redocly.yaml
|
||||
apiDefinitions:
|
||||
petstore: ./openapi/petstore-definition.json
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
#### Specify config file
|
||||
### Custom configuration 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
|
||||
openapi stats --config=./another/directory/config.yaml
|
||||
```
|
||||
|
||||
### Format
|
||||
|
||||
#### Stylish (default)
|
||||
|
||||
```bash request
|
||||
openapi stats pet.yaml
|
||||
```
|
||||
|
||||
```bash output
|
||||
Document: pet.yaml stats:
|
||||
|
||||
🚗 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.
|
||||
|
||||
Reference in New Issue
Block a user