LukeParke/redocly-cli
1
0
Fork 0
mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-06 04:21:09 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
afb5d9425f755f45ad4cb9aa930410f49b660181
redocly-cli/docs/rules/spec-strict-refs.md
Lorna Jane Mitchell de80612b55 chore: Run prettier on all docs files (#1334)
2023-11-17 09:45:03 +00:00

2.3 KiB
Raw Blame History

slug
slug
/docs/cli/rules/spec-strict-refs

spec-strict-refs

Checks that $ref is only used in the locations permitted by the OpenAPI specification.

OAS Compatibility
2.0 ✅
3.0 ✅
3.1 ✅

API design principles

This rule ensures adherence to OpenAPI specification standards.

It limits use of the $ref keyword to only references for elements that may be inside the component section.

This rule is useful when other tools are integrated into the API workflow that demand strict adherence to the specifications.

The following is a list of elements the $ref can be used with according to the OpenAPI specification:

  • Schema
  • Response
  • Parameter
  • Example
  • RequestBody
  • Header
  • SecurityScheme
  • Link
  • Callback
  • PathItem

Configuration

To configure the rule, add it to the rules object in your configuration file, and set the desired severity.

Option Type Description
severity string Possible values: off, warn, error. Default off (in recommended configuration).

An example configuration:

rules:
  spec-strict-refs: error

Examples

Given the following configuration:

rules:
  spec-strict-refs: error

Example of incorrect use of $ref:

responses:
  '200':
    description: successful operation
    content:
      application/json:
        schema:
          type: object
          properties:
            $ref: './properties.yaml'
            name:
              type: string

Example of correct use of $ref:

responses:
  '200':
    description: successful operation
    content:
      application/json:
        schema:
          $ref: './properties.yaml'

Related rules

Resources