Skip to content

Commit 56a31bd

Browse files
AlbinaBlazhko17AlbinaBlazhko17
authored
feat: implement scorecard-classic command (#2433)
1 parent 3dca88e commit 56a31bd

File tree

18 files changed

+2227
-1
lines changed

18 files changed

+2227
-1
lines changed

‎.changeset/sixty-trams-show.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@redocly/cli": patch
3+
---
4+
5+
Added `scorecard-classic` command to evaluate API descriptions against project scorecard configurations.

‎docs/@v2/commands/scorecard-classic.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# `scorecard-classic`
2+
3+
## Introduction
4+
5+
The `scorecard-classic` command evaluates your API descriptions against quality standards defined in your Redocly project's scorecard configuration.
6+
Use this command to validate API quality and track compliance with organizational governance standards across multiple severity levels.
7+
8+
{% admonition type="info" name="Note" %}
9+
The `scorecard-classic` command requires a scorecard configuration in your Redocly project. You can configure this in your project settings or by providing a `--project-url` flag. Learn more about [configuring scorecards](https://redocly.com/docs/realm/config/scorecard).
10+
{% /admonition %}
11+
12+
## Usage
13+
14+
```bash
15+
redocly scorecard-classic <api> --project-url=<url>
16+
redocly scorecard-classic <api> --config=<path>
17+
redocly scorecard-classic <api> --format=json
18+
redocly scorecard-classic <api> --target-level=<level>
19+
redocly scorecard-classic <api> --verbose
20+
```
21+
22+
## Options
23+
24+
| Option | Type | Description |
25+
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26+
| api | string | Path to the API description filename or alias that you want to evaluate. See [the API section](#specify-api) for more details. |
27+
| --config | string | Specify path to the [configuration file](#use-alternative-configuration-file). |
28+
| --format | string | Format for the output.<br />**Possible values:** `stylish`, `json`. Default value is `stylish`. |
29+
| --help | boolean | Show help. |
30+
| --project-url | string | URL to the project scorecard configuration. Required if not configured in the Redocly configuration file. Example: `https://app.cloud.redocly.com/org/my-org/projects/my-project/scorecard-classic`. |
31+
| --target-level | string | Target scorecard level to achieve. The command validates that the API meets this level and all preceding levels without errors. Exits with an error if the target level is not achieved. |
32+
| --verbose, -v | boolean | Run the command in verbose mode to display additional information during execution. |
33+
34+
## Examples
35+
36+
### Specify API
37+
38+
You can use the `scorecard-classic` command with an OpenAPI description file path or an API alias defined in your Redocly configuration file.
39+
40+
```bash
41+
redocly scorecard-classic openapi/openapi.yaml --project-url=https://app.cloud.redocly.com/org/my-org/projects/my-project/scorecard-classic
42+
```
43+
44+
In this example, `scorecard-classic` evaluates the specified API description against the scorecard rules defined in the provided project URL.
45+
46+
### Use alternative configuration file
47+
48+
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory.
49+
Use the optional `--config` argument to provide an alternative path to a configuration file.
50+
51+
```bash
52+
redocly scorecard-classic openapi/openapi.yaml --config=./another/directory/redocly.yaml
53+
```
54+
55+
### Configure scorecard in redocly.yaml
56+
57+
You can configure the scorecard project URL in your Redocly configuration file to avoid passing it as a command-line argument:
58+
59+
```yaml
60+
scorecard:
61+
fromProjectUrl: https://app.cloud.redocly.com/org/my-org/projects/my-project/scorecard-classic
62+
63+
apis:
64+
core@v1:
65+
root: ./openapi/api-description.json
66+
```
67+
68+
With this configuration, you can run the command without the `--project-url` flag:
69+
70+
```bash
71+
redocly scorecard-classic core@v1
72+
```
73+
74+
### Use JSON output format
75+
76+
To generate machine-readable output suitable for CI/CD pipelines or further processing, use the JSON format:
77+
78+
```bash
79+
redocly scorecard-classic openapi/openapi.yaml --format=json
80+
```
81+
82+
The JSON output is grouped by scorecard level and includes:
83+
84+
- version information
85+
- achieved scorecard level
86+
- summary of errors and warnings for each level
87+
- rule ID and documentation link (for built-in rules)
88+
- severity level (error or warning)
89+
- location information (file path, line/column range, and JSON pointer)
90+
- descriptive message about the violation
91+
92+
### Validate against a target level
93+
94+
Use the `--target-level` option to ensure your API meets a specific quality level. The command validates that your API satisfies the target level and all preceding levels without errors:
95+
96+
```bash
97+
redocly scorecard-classic openapi/openapi.yaml --target-level=Gold
98+
```
99+
100+
If the API doesn't meet the target level, the command:
101+
102+
- displays which level was actually achieved
103+
- shows all validation issues preventing the target level from being met
104+
- exits with a non-zero exit code (useful for CI/CD pipelines)
105+
106+
This is particularly useful in CI/CD pipelines to enforce minimum quality standards before deployment.
107+
108+
### Run in verbose mode
109+
110+
For troubleshooting or detailed insights into the scorecard evaluation process, enable verbose mode:
111+
112+
```bash
113+
redocly scorecard-classic openapi/openapi.yaml --verbose
114+
```
115+
116+
Verbose mode displays additional information such as:
117+
118+
- project URL being used
119+
- authentication status
120+
- detailed logging of the evaluation process
121+
122+
## Authentication
123+
124+
The `scorecard-classic` command requires authentication to access your project's scorecard configuration.
125+
You can authenticate in one of two ways:
126+
127+
### Using API key (recommended for CI/CD)
128+
129+
Set the `REDOCLY_AUTHORIZATION` environment variable with your API key:
130+
131+
```bash
132+
export REDOCLY_AUTHORIZATION=your-api-key-here
133+
redocly scorecard-classic openapi/openapi.yaml
134+
```
135+
136+
### Interactive login
137+
138+
If no API key is provided, the command prompts you to log in interactively:
139+
140+
```bash
141+
redocly scorecard-classic openapi/openapi.yaml
142+
```
143+
144+
The CLI opens a browser window for you to authenticate with your Redocly account.
145+
146+
## Scorecard results
147+
148+
The scorecard evaluation categorizes issues into multiple levels based on your project's configuration.
149+
Each issue is associated with a specific scorecard level, allowing you to prioritize improvements.
150+
151+
The command displays the achieved scorecard level, which is the highest level your API meets without errors.
152+
The achieved level is shown in both stylish and JSON output formats.
153+
154+
When all checks pass, the command displays a success message:
155+
156+
```text
157+
☑️ Achieved Level: Gold
158+
159+
✅ No issues found for openapi/openapi.yaml. Your API meets all scorecard requirements.
160+
```
161+
162+
When issues are found, the output shows:
163+
164+
- the achieved scorecard level
165+
- the rule that was violated
166+
- the scorecard level of the rule
167+
- the location in the API description where the issue occurs
168+
- a descriptive message explaining the violation
169+
170+
If a `--target-level` is specified and not achieved, the command displays an error message and exits with a non-zero code.
171+
172+
## Related commands
173+
174+
- [`lint`](./lint.md) - Standard linting for API descriptions with pass/fail results
175+
- [`bundle`](./bundle.md) - Bundle multi-file API descriptions into a single file
176+
- [`stats`](./stats.md) - Display statistics about your API description structure
177+
178+
## Resources
179+
180+
- [API governance documentation](../api-standards.md)
181+
- [Redocly configuration guide](../configuration/index.md)
182+
- [Custom rules and plugins](../custom-plugins/index.md)

‎docs/@v2/v2.sidebars.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@
3434
page: commands/push-status.md
3535
- label: respect
3636
page: commands/respect.md
37+
- label: scorecard-classic
38+
page: commands/scorecard-classic.md
3739
- label: split
3840
page: commands/split.md
3941
- label: stats

0 commit comments

Comments
 (0)