OpenAPITools / OpenAPITools/openapi-generator
[BUG] OAS Validation should report an error when $ref uses '#/definitions'
Nobody has claimed this yet.
- 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
- unzip this file
oas-validation-issue-def.zip - run
./gradlew clean build
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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