swagger-api / swagger-api/swagger-parser
Refs not resolved in components when paths are not present
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 867
- Forks
- 560
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 7
Description
Originally flagged here: https://github.com/swagger-api/swagger-parser/issues/664#issuecomment-479464930
References in components are only resolved when the paths object is present with referenced schemas. References should resolve for components when just the components object is present.
So when I have:
val yaml = "openapi: 3.0.0\n" +
"info:\n" +
" version: 0.0.0\n" +
" title: Simple API\n" +
"components:\n" +
" schemas:\n" +
" Product:\n" +
" properties:\n" +
" product_id:\n" +
" type: string\n" +
" description: >-\n" +
" Unique identifier representing a specific product for a given\n" +
" latitude & longitude. For example, uberX in San Francisco will have\n" +
" a different product_id than uberX in Los Angeles.\n" +
" Bag:\n" +
" type: array\n" +
" items:\n" +
" $ref: '#/components/schemas/Product'";
val parser = new OpenAPIV3Parser
val options = new ParseOptions
options.setResolveFully(true)
val openAPI = parser.readContents(yaml, null, options).getOpenAPI
println(openAPI.getComponents.getSchemas.get("Bag").toString)
The references are never resolved, the output of the Bag Schema is:
class ArraySchema {
class Schema {
type: array
format: null
$ref: null
description: null
title: null
multipleOf: null
maximum: null
exclusiveMaximum: null
minimum: null
exclusiveMinimum: null
maxLength: null
minLength: null
pattern: null
maxItems: null
minItems: null
uniqueItems: null
maxProperties: null
minProperties: null
required: null
not: null
properties: null
additionalProperties: null
nullable: null
readOnly: null
writeOnly: null
example: null
externalDocs: null
deprecated: null
discriminator: null
xml: null
}
items: class Schema {
type: null
format: null
$ref: #/components/schemas/Product
description: null
title: null
multipleOf: null
maximum: null
exclusiveMaximum: null
minimum: null
exclusiveMinimum: null
maxLength: null
minLength: null
pattern: null
maxItems: null
minItems: null
uniqueItems: null
maxProperties: null
minProperties: null
required: null
not: null
properties: null
additionalProperties: null
nullable: null
readOnly: null
writeOnly: null
example: null
externalDocs: null
deprecated: null
discriminator: null
xml: null
}
}
However when paths are included, referring the schemas, it does resolve the references, so when I have:
val yaml = "openapi: 3.0.0\n" +
"info:\n" +
" version: 0.0.0\n" +
" title: Simple API\n" +
"paths:\n" +
" /:\n" +
" get:\n" +
" responses:\n" +
" '200':\n" +
" description: OK\n" +
" content:\n" +
" '*/*':\n" +
" schema:\n" +
" $ref: '#/components/schemas/Bag'\n" +
"components:\n" +
" schemas:\n" +
" Product:\n" +
" properties:\n" +
" product_id:\n" +
" type: string\n" +
" description: >-\n" +
" Unique identifier representing a specific product for a given\n" +
" latitude & longitude. For example, uberX in San Francisco will have\n" +
" a different product_id than uberX in Los Angeles.\n" +
" Bag:\n" +
" type: array\n" +
" items:\n" +
" $ref: '#/components/schemas/Product'";
The output is:
class ArraySchema {
class Schema {
type: array
format: null
$ref: null
description: null
title: null
multipleOf: null
maximum: null
exclusiveMaximum: null
minimum: null
exclusiveMinimum: null
maxLength: null
minLength: null
pattern: null
maxItems: null
minItems: null
uniqueItems: null
maxProperties: null
minProperties: null
required: null
not: null
properties: null
additionalProperties: null
nullable: null
readOnly: null
writeOnly: null
example: null
externalDocs: null
deprecated: null
discriminator: null
xml: null
}
items: class Schema {
type: null
format: null
$ref: null
description: null
title: null
multipleOf: null
maximum: null
exclusiveMaximum: null
minimum: null
exclusiveMinimum: null
maxLength: null
minLength: null
pattern: null
maxItems: null
minItems: null
uniqueItems: null
maxProperties: null
minProperties: null
required: null
not: null
properties: {product_id=class StringSchema {
class Schema {
type: string
format: null
$ref: null
description: Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.
title: null
multipleOf: null
maximum: null
exclusiveMaximum: null
minimum: null
exclusiveMinimum: null
maxLength: null
minLength: null
pattern: null
maxItems: null
minItems: null
uniqueItems: null
maxProperties: null
minProperties: null
required: null
not: null
properties: null
additionalProperties: null
nullable: null
readOnly: null
writeOnly: null
example: null
externalDocs: null
deprecated: null
discriminator: null
xml: null
}
}}
additionalProperties: null
nullable: null
readOnly: null
writeOnly: null
example: null
externalDocs: null
deprecated: null
discriminator: null
xml: null
}
}
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 OpenAPIV3Parser and ParseOptions usage shown in the report, then trace how setResolveFully(true) processes schemas under components when paths is absent. Reproduce both YAML cases and make the components-only case resolve the Bag items reference consistently with the paths case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100