OpenAPITools / OpenAPITools/openapi-generator

[BUG] OAS Validation should report an error when $ref uses '#/definitions'

Open
#10,482 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Description

I'm using the gradle 5.2.1 plugin for validating my API

When my API references a type with a prefix of '#/definitions', I'd expect for the validator to report errors, but that's not the case

        - in: query
          name: pageable
          style: form
          explode: true
          schema:
            $ref: "#/definitions/Pageable"

Here is the output

./gradlew build

> Task :openApiValidate
Validating spec /home/adrian/dev/pai-api-v1/src/main/open-api/pai-api-v1.yaml
Spec is valid.

I get the right report (an error) when using the online tools (https://editor.swagger.io/ or https://apitools.dev/swagger-parser/online/):

Semantic error at paths./factures.get.parameters.1.schema.$ref
$refs must reference a valid location in the document
openapi-generator version

5.2.1

OpenAPI declaration file content or url
openapi: 3.0.1
info:
  title: Bla
  description: Bla
  version: "@VERSION@"
servers:
- url: '/api/v1'
paths:
  /factures:
    get:
      summary: liste des factures
      operationId: listerFactures
      parameters:
        - name: codesApprenants
          in: query
          description: les codes apprenants
          schema:
            type: array
            items:
              type: string
        - in: query
          name: pageable
          style: form
          explode: true
          schema:
            $ref: "#/definitions/Pageable"
      responses:
        200:
          description: liste des factures
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Factures'
        404:
          description: Structure introuvable

components:

 schemas:

  Factures:
    properties:
      items:
        type: array
        items:
          $ref: '#/components/schemas/Facture'

  Facture:
    type: object
    properties:
      dateGeneration:
        type: string
        format: date
        description: La date de génération de la ventilation de droits.
Steps to reproduce

You should see the following report (no issue)

> Task :openApiValidate
Validating spec /home/adrian/dev/oas-validation-issue-def/sample.yaml
Spec is valid.

BUILD SUCCESSFUL

We would expect an error during validation

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the sample.yaml reproduction from the attached archive and run ./gradlew clean build, focusing on the openApiValidate task. Trace the validator entry point used by the Gradle 5.2.1 plugin and compare handling of the #/definitions/Pageable reference with the valid #/components/schemas references. Done means the build reports the invalid reference as an error.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.