search

daveshanley / vacuum

vacuum is the worlds fastest OpenAPI 3, OpenAPI 2 / Swagger linter and quality analysis tool. Built in go, it tears through API specs faster than you can think. vacuum is compatible with Spectral rulesets and generates compatible reports.
https://quobix.com/vacuum
MIT License
634 stars 51 forks source link

allow vendor extensions next to $refs #586

Open BentEngbers opened 1 week ago

BentEngbers commented 1 week ago

In the following example, vacuum reports an oas3-no-$ref-siblings error.

openapi: 3.1.0
paths:
  /example:
    get:
      operationId: example
      responses:
        "200":
          content:
            application/json:
              schema:
                x-test: foo
                $ref: "#/components/schemas/response"
components:
  schemas:
    response:
      type: string

The error: 

 a `$ref` can only be placed next to `summary` and `description` but got:x-test      | oas3-no-$ref-siblings
LasneF commented 6 days ago

looking on the rules here https://learn.openapis.org/referencing/overview.html#a-taxonomy-of-references

summary and description has an explicit specification , whereas it has not for extension

the key being if the reference should override the parent or not , this behavior is only specified for description and summary

then to me the rule as it is looks fair ,

2 options for work around : @BentEngbers disable the rules as it does not suits your need @daveshanley having a mechanism of rules extension so that the end user can add others key word to the rules (may be simple to say , but complex to specify with dedicated configuration file/ model )