{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"stats","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," command provides statistics about the structure of one or more API description files."," ","This command generates statistics for the following metrics:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["References"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["External Documents"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Schemas"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parameters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Links"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Path Items"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Operations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tags"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're interested in the technical details, the statistics are calculated using the counting logic from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StatsVisitor"]}," module."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage","__idx":2},"children":["Usage"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly stats <api>\nredocly stats <api> [--format=<option>] [--config=<path>]\nredocly stats --version\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":3},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["api"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Path to the API description filename or alias that you want to generate the statistics for. Refer to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#specify-api"},"children":["the API section"]}," for more details."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify path to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#use-alternative-configuration-file"},"children":["configuration file"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Format for the output.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stylish"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["markdown"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stylish"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--help"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show help."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--lint-config"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specify the severity level for the configuration file. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Possible values:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},". Default value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["--version"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show version number."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":4},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specify-api","__idx":5},"children":["Specify API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," command behaves differently depending on how you pass the API to it, and whether the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#use-alternative-configuration-file"},"children":["configuration file"]}," exists."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"pass-an-api-directly","__idx":6},"children":["Pass an API directly"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," command with an OpenAPI description directly, with a command like the following:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly stats openapi/openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this case, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," shows statistics for the API description that was passed in."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"pass-an-api-alias","__idx":7},"children":["Pass an API alias"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead of a full path, you can use an API name from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," section of your Redocly configuration file."," ","For example, with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration file containing the following entry for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core@v1"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n  core@v1:\n    root: ./openapi/api-description.json\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can obtain the statistics by giving the API alias name, as shown below:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly stats core@v1\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this case, after resolving the path behind the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core@v1"]}," name, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," displays statistics for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi/api-description.json"]}," file. For this approach, the Redocly configuration file is mandatory."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-alternative-configuration-file","__idx":8},"children":["Use alternative configuration file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the CLI tool looks for the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1/configuration"},"children":["Redocly configuration file"]}," in the current working directory. Use the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--config"]}," argument to provide an alternative path to a configuration file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly stats --config=./another/directory/config.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specify-output-format","__idx":9},"children":["Specify output format"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"specify-the-stylish-default-output-format","__idx":10},"children":["Specify the stylish (default) output format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default output format for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," is called \"stylish\"."," ","It outputs a nice format for your terminal, as shown in the following example:"]},{"$$mdtype":"Tag","name":"pre","attributes":{},"children":["\nDocument: museum.yaml stats:\n\n🚗 References: 35\n📦 External Documents: 0\n📈 Schemas: 23\n👉 Parameters: 6\n🔗 Links: 0\n🔀 Path Items: 5\n👷 Operations: 8\n🔖 Tags: 3\n\nmuseum.yaml: stats processed in 4ms\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this format, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," shows the statistics in a condensed but readable manner with an icon at the beginning of each line."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"specify-the-json-output-format","__idx":11},"children":["Specify the JSON output format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--format=json"]}," to get a machine-readable output format."," ","The JSON format output is shown in the following example:"]},{"$$mdtype":"Tag","name":"pre","attributes":{},"children":["\n{\n  \"refs\": {\n    \"metric\": \"🚗 References\",\n    \"total\": 35\n  },\n  \"externalDocs\": {\n    \"metric\": \"📦 External Documents\",\n    \"total\": 0\n  },\n  \"schemas\": {\n    \"metric\": \"📈 Schemas\",\n    \"total\": 23\n  },\n  \"parameters\": {\n    \"metric\": \"👉 Parameters\",\n    \"total\": 6\n  },\n  \"links\": {\n    \"metric\": \"🔗 Links\",\n    \"total\": 0\n  },\n  \"pathItems\": {\n    \"metric\": \"🔀 Path Items\",\n    \"total\": 5\n  },\n  \"operations\": {\n    \"metric\": \"👷 Operations\",\n    \"total\": 8\n  },\n  \"tags\": {\n    \"metric\": \"🔖 Tags\",\n    \"total\": 3\n  }\n}\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The JSON format output is suitable when you want to use the stats data in another program."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"specify-the-markdown-output-format","__idx":12},"children":["Specify the Markdown output format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--format=markdown"]}," to return output that you can use in Markdown files or other Markdown-friendly applications."," ","A table format is used."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is an example source output:"]},{"$$mdtype":"Tag","name":"pre","attributes":{},"children":["\n| Feature  | Count  |\n| --- | --- |\n| 🚗 References | 35 |\n| 📦 External Documents | 0 |\n| 📈 Schemas | 23 |\n| 👉 Parameters | 6 |\n| 🔗 Links | 0 |\n| 🔀 Path Items | 5 |\n| 👷 Operations | 8 |\n| 🔖 Tags | 3 |\n\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's the rendered example source output:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Feature"},"children":["Feature"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Count"},"children":["Count"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["🚗 References"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["35"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["📦 External Documents"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["0"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["📈 Schemas"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["23"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["👉 Parameters"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["6"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["🔗 Links"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["0"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["🔀 Path Items"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["👷 Operations"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["8"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["🔖 Tags"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows how to use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," command in a GitHub action to make a ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/"},"children":["GitHub summary"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"name: Get API stats\non: push\n\njobs:\n  get_stats:\n    name: Stats as a job summary\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check out repo's default branch\n        uses: actions/checkout@v4\n      - name: Set up node\n        uses: actions/setup-node@v4\n      - name: Install Redocly CLI\n        run: npm install -g @redocly/cli@latest\n      - name: Get stats\n        run: redocly stats --format=markdown museum.yaml >> $GITHUB_STEP_SUMMARY 2>&1\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This GitHub action uses the output of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stats"]}," command in Markdown format as the input value for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$GITHUB_STEP_SUMMARY"]},"."," ","When the job is complete, your API stats are added to the summary page, as shown in the following screenshot:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/stats-github-job-summary-5cdb5c30ee64b146.png","alt":"GitHub job summary showing API stats"},"children":[]}]}]},"frontmatter":{},"tagList":["html"],"title":"stats","lastModified":"2025-05-28T16:01:32.000Z"}