Configure scorecard

In Reunite, you can configure the scorecard feature to evaluate your API description files against rules. Reunite includes the following three built-in rulesets:

• minimal: The minimal ruleset is a good starting point for an existing API that doesn't currently conform to any standard. It has fewer rules that cause an error, with others either downgraded to a warning or turned off completely.
• recommended: The recommended ruleset is our unabashedly opinionated recommendation of what we think a good API looks like. It's a great place to start, before adapting to your own context.
• recommended-strict: The recommended-strict ruleset is identical to the recommended ruleset, except it elevates all warnings to errors. It's the ideal option for those who don't want to miss anything.

You can use these rulesets only, or extend them with custom rules according to your needs.

Before you begin

Make sure you have the following before you begin:

• a redocly.yaml configuration file

Add scorecard to your project with Redocly rulesets

To add a scorecard to your project using only the built-in rules:

1. Add the following configuration to your redocly.yaml file:

   redocly.yaml

   scorecard:
     levels: # an ordered list of levels (from lowest to highest)
       - name: Baseline
         extends:
           - minimal
       - name: Superior
         extends:
           - recommended
   

2. (Optional) You can change the level name values to suit your project.

3. Commit and merge your changes.

After you commit, the scorecard information displays in Reunite and the preview build. When you merge and the production deploy completes, the scorecard labels and reports also display on your production environment.

Configure custom scorecard rulesets

Instead of using Redocly's built-in rulesets, you can define your own scorecard levels and build rulesets with your criteria. Building rules in Reunite is very similar to building API standard rulesets in Redocly CLI.

Configure scorecard rulesets in redocly.yaml

If you have a small amount of custom rules and you want to include them all in the redocly.yaml file you can add your rules directly.

To configure custom rules in redocly.yaml:

1. Add the following configuration to your redocly.yaml file:

   redocly.yaml

   scorecard:
     levels:
   

2. For each level you want to add, add the following configuration:

   redocly.yaml

       - name: # provide a name for the ruleset
         rules:
   

   The levels should be listed in order from the lowest to the highest.

3. In the rules object, add a map of rules. You can use any combination of Redocly's built-in rules or create configurable rules.

   Example:

   redocly.yaml

   scorecard:
     levels:
     - name: Baseline
         rules: # The following rules are built-in rules with their severity set to error
           no-unresolved-refs: error # This rule checks that the $ref mentioned in the description exists
           no-server-example.com: error # This rule checks that example.com is not being used for the server URL
     - name: Superior
         rules: # The following rules are built-in rules except for rule/operation-summary-min-length, which is a configurable rule
           no-unresolved-refs: error
           no-unused-components: error # This rule checks to make sure all components listed in the description are used
           no-server-example.com: error
           rule/operation-summary-min-length: # This configurable rule checks that the summary for an operation OpenAPI node type is at least 20 characters in length
             subject:
               type: Operation
               property: summary
             message: Operation summary must have minimum of 20 chars length
             assertions:
               minLength: 20
   

4. Commit and merge your changes.

After you commit, the scorecard information displays in Reunite and the preview build. When you merge and the production deploy completes, the scorecard labels and reports also display on your production environment.

Configure scorecard rulesets in separate files

If you have many rulesets or your rulesets are complex, you can put them into separate YAML files. Putting your rulesets in different files means you can have one file per scorecard level, making it easier to maintain rule sets and your redocly.yaml file.

To configure scorecard rulesets in separate files:

1. Create a YAML file for each scorecard levels you want to add.

2. In each of the files, add a rules object and a map of rules for this scorecard level. You can use any combination of Redocly's built-in rules or create configurable rules.

   Example:

   api-ruleset-baseline.yaml

     rules:
       no-empty-servers: warn
       rule/info-description-property-defined: # This configurable rule enforces the inclusion of a description the the info OpenAPI node type
         subject:
           type: Info
           property: description
         assertions:
           defined: true
         severity: warning
       boolean-parameter-prefixes: # This built-in rule enforces specific and consistent naming for request parameters with boolean type by requiring they all start with "is" or "can"
         severity: error
         prefixes:
           - is
           - can
       info-license: error # This built-in rule enforces the license section of the info OpenAPI node type to be defined
       info-license-url: error # This built-in rule enforces a url be included in the license section of the info OpenAPI node type
   

3. Add the following configuration to your redocly.yaml file:

   scorecard:
     levels:
   

4. For each level, add a name object and an extends object with a path to the ruleset file.

   Example:

   redocly.yaml

   scorecard:
     levels:
       - name: Baseline
         extends:
           - ./api-ruleset-baseline.yaml
         rules:
           boolean-parameter-prefixes: # This turns off the boolean-parameter-prefixes rule for the baseline ruleset
             severity: off
       - name: Silver
         extends:
           - ./api-ruleset-silver.yaml
       - name: Gold
         extends:
           - ./api-ruleset-gold.yaml
   

5. Commit and merge your changes.

After you commit, the scorecard information displays in Reunite and the preview build. When you merge and the production deploy completes, the scorecard labels and reports also display on your production environment.

Publish project with non-compliant APIs

By default, if one or more of your API description files does not comply with the rules in the lowest level ruleset, your project's build will be success, but the deploy will be blocked to published to production. In certain situations, you might want to bypass this behavior.

To publish projects with non-compliant APIs:

1. In redocly.yaml, inside reunite add the ignoreLint: true parameter, as in the following example:

   redocly.yaml

   reunite:
     ignoreLint: true
   

2. Commit and merge your changes.

After the production build finishes, the APIs that do not meet the lowest level criteria are marked with a "Non-compliant" label in Reunite and on your published project.

Exclude APIs from scorecard

The scorecard feature evaluates all API description files in your project, regardless of their location in the file tree. You might want to exclude APIs that are still being developed, or sample APIs you use for training or testing.

If you have APIs you want to exclude from evaluation, list the API description files' locations in the ignore object in redocly.yaml.

To exclude API description files from scorecard and publishing:

1. In your redocly.yaml file, add an ignore object.

2. Inside the object, add an array of paths to the API description files to exclude.

   For example:

   redocly.yaml

   ignore:
     - ./apis/WIP/my-work-in-progress.yaml 
     - ./test-api2.yaml
     - ./internal/projects/user-management.yaml
   

3. Commit and merge your changes.

After you publish the updated project, the listed API description files are excluded from the scorecard reports in Reunite and on your published project.

Related how-tos

• Follow the steps in Add OpenAPI descriptions to add your OpenAPI descriptions to your project.
• If you have a lot of API descriptions, Add a catalog for an organized way to display them in your project.

Resources

• Learn more about the Scorecard feature including what it displays and where to find the reports.
• Check out the Scorecard reference page to see the different options you can configure.