3.0 refs not resolving when the second route points to any ref that is same as first
See original GitHub issueHello, I have a strange issue i just ran into and I’m hoping you can help.
I’m using swagger-parser
6.0.1
Below is a full example. In my global.yml i have the following:
openapi: 3.0.0
info:
title: Swagger API
version: 48.0.0
servers:
- url: '{scheme}://localhost:4444'
description: Development server (uses dev data for SQL)
variables:
scheme:
description: Dev API scheme.
enum:
- https
- http
default: http
- url: '{scheme}://localhost:3333'
description: Sandbox server (uses test data)
variables:
scheme:
description: Test API scheme.
enum:
- https
- http
default: http
paths:
/errors/item/new:
$ref: 'paths/ops/errors/item/item_new.yml'
/errors/item/edit:
$ref: 'paths/ops/errors/item/item_edit.yml'
Everything for ref for /errors/item/new
resolves fine. Here is a example of that file
post:
summary: Create new item error...
tags:
- OPS API
- Errors API
- item
description: 'something'
requestBody:
content:
application/json:
schema:
type: object
required:
$ref: 'schema_required_new.yml#/required'
properties:
$ref: 'schema_required_new.yml#/properties'
example:
$ref: 'schema_example_new.yml'
responses:
'200':
description: Returns success confirmation message...
'400':
description: Bad request....
content:
application/json:
schema:
$ref: '../../../../models/error.yml'
'401':
description: Authorization information is missing or invalid...
content:
application/json:
schema:
$ref: '../../../../models/error.yml'
The problem is the next file does not resolve any refs properly that were being used by the first. In my test, the second file (/errors/item/edit:
) won’t resolve any files that were referenced in the first file.
Assume that /errors/item/edit:
file reference is a duplicate of the first, here is example output when i run swagger-cli bundle global.yml -o openapi_full.yml -t yaml
openapi: 3.0.1
info:
title: Swagger API
version: 48.0.0
servers:
- url: '{scheme}://localhost:4444'
description: Development server (uses dev data for SQL)
variables:
scheme:
description: Dev API scheme.
enum:
- https
- http
default: http
- url: '{scheme}://localhost:3333'
description: Sandbox server (uses test data)
variables:
scheme:
description: Test API scheme.
enum:
- https
- http
default: http
paths:
/errors/item/new:
post:
summary: Create new item error...
tags:
- OPS API - Errors API - item
description: something
requestBody:
content:
application/json:
schema:
type: object
required:
- defectType
- date
- itemSku
- defectCause
- numDefective
- costPerOccurrence
- itemManufacturer
- manufacturerCredit
- returned
- marketplace
- note
- recordStatus
properties:
id:
type: string
description: >-
This should be the associated object ID of the id of the
error to edit when editing.
defectType:
type: string
description: >-
This should be the associated object ID of the defectType
(same as error type).
date:
type: string
itemSku:
type: string
defectCause:
type: string
numDefective:
type: integer
costPerOccurrence:
type: number
description: >-
Should autopopulate after user enter itemSku (Do lookup with
item-by-itemnum/:item_number)
itemManufacturer:
type: string
description: >-
Should autopopulate after user enter itemSku (Do lookup with
item-by-itemnum/:item_number)
manufacturerCredit:
type: boolean
returned:
type: boolean
marketplace:
type: integer
refOrderNum:
type: string
refRmaNum:
type: string
note:
type: string
recordStatus:
type: integer
example:
defectType: asdfasdfasdfasdfasfd
date: '2008-09-15T15:53:00'
itemSku: 10326
defectCause: something test on word tyt
numDefective: 1
costPerOccurrence: 8
itemManufacturer: Ningbo
manufacturerCredit: true
returned: false
marketplace: Other
refOrderNum: none
refRmaNum: none
note: A test note
recordStatus: 1
responses:
'200':
description: Returns success confirmation message...
'400':
description: Bad request....
'401':
description: Authorization information is missing or invalid...
content:
application/json:
schema:
required:
- error
properties:
error:
type: string
message:
type: string
/errors/item/edit:
post:
summary: Edit item error...
tags:
- OPS API - Errors API - item
description: something
requestBody:
content:
application/json:
schema:
type: object
required:
$ref: >-
#/paths/~1errors~1item~1new/post/requestBody/content/application~1json/schema/required
properties:
$ref: >-
#/paths/~1errors~1item~1new/post/requestBody/content/application~1json/schema/properties
example:
$ref: >-
#/paths/~1errors~1item~1new/post/requestBody/content/application~1json/schema/example
responses:
'200':
description: Returns success confirmation message...
'400':
description: Bad request....
'401':
description: Authorization information is missing or invalid...
All the references in the second route are resolving improperly. They end up like 1errors~1item~1new/post/requestBody/content/application~1json/schema/required
instead of resolving the reference.
I don’t need them to use the same ref
for anything but schema properties
. If i change the reference file for schema required
and schema example
to be a uniq file that is not used anywhere else, the problem goes away for those, but i need to reuse the schema properties
to get rid of duplicate code. I have the same problem when i moved it into model and tried to reference it there. Am I doing something wrong?
Issue Analytics
- State:
- Created 5 years ago
- Comments:6 (3 by maintainers)
Top GitHub Comments
Yes, all of my Swagger/OpenAPI libraries allow
$ref
pointers anywhere, and this is very much intentional. There are two reasons for this:Like you, I need to be able to split my API definitions up in many different ways, and the
$ref
locations that are allowed by the OpenAPI Spec are simply not flexible enoughAll of my libraries use json-schema-ref-parser under the hood, which is a general purpose JSON Schema library and is not limited to Swagger/OpenAPI files. The JSON Schema spec allows
$ref
pointers to be used anywhere.As you’ve noticed, however, this flexibility can lead to compatibility issues with other tools. Some tools only support
$ref
pointers in the places that are explicitly defined in the spec. Other tools don’t support$ref
pointers at all. There are two solutions for this:Use
bundle --dereference
to remove all$ref
pointers. This ensures that your API definition can be used by any tool.Use
bundle
, but be sure to build your API definition in such a way that the resulting bundle only has$ref
pointers in places that are allowed by the spec. This approach is more complicated. It relies on the deterministic behavior of thebundle
algorithm. The algorithm will always choose the shortest possible$ref
as the “master”, and all other$refs
to the same value will be rewritten to point to the master$ref
.@JamesMessinger, so the issue is that I was using
ref
in a place that OpenAPI spec does not say it can be used.swagger-ui
only supportsrefs
in the places specified by OpenAPI.With that said, your tool lets users use
refs
just about anywhere (which is awesome!). This is great because I can break up my files in may different ways (and use refs in places likerequired
,properties
,example
, etc). Usingdereference
(viaswagger-cli
) makes things compliant.Is allowing the use of
refs
anywhere (or at least the way im using it) andswagger-parser bundle
orswagger-cli bundle --dereference
resolving all the refs intentional? I just want to make sure I’m not digging myself a future whole with the way I’m building out my documentation.