Out of the three statements, only b) is true.
The spec does allow internal references.
Your first reference sample is mostly valid, only it needs to be escaped:
$ref: "#/paths/~1request1".
You can technically also contain Path Items Objects in an extension and
reference those locally.
JSON References are parsed based on their location. This is not an “include”
operation.
So if you have a relative reference insides a referenced document, it will be
relative to the referenced document.
In your example:
commonrequest.yaml content:
---
get:
responses:
200:
description: OK
schema:
$ref: "#/components/schemas/schema1"
...
$ref: "#/components/schemas/schema1" is referencing
“#/components/schemas/schema1” inside commomnrequest.yaml regardless if
commonrequest.yaml is referenced from a different file. That’s just how JSON
References are resolved.
From: <swagger-swaggersocket@googlegroups.com> on behalf of Andy Schmidt
<argos.netwo...@gmail.com>
Reply-To: "swagger-swaggersocket@googlegroups.com"
<swagger-swaggersocket@googlegroups.com>
Date: Thursday, November 9, 2017 at 15:42
To: Swagger <swagger-swaggersocket@googlegroups.com>
Subject: OAS 3.0 - PATH object reference impractical?
Hi,
After working on this for a few days, researching various
discussions/suggestions on splitting up "Swagger" definitions, I find myself
wondering if the current specifications for "PATH" object references are not at
all practical.
Here is what I believe to be true as far as reusability of PATH objects:
a) PATH object references are NOT permitted to be internal - they MUST be
external.
b) PATH object references cannot use the "component" tree, because component
can't hold path objects.
c) PATH object references MUST be external - for no apparent reason (at least
to this lay person).
To illustrate those three points, I believe only the final reference to be
valid under the specifications:
paths:
/request1:
get:
responses:
200:
description: OK
schema:
$ref: "#/components/schemas/schema1"
/request/{id1}:
$ref "#/paths/request1" # internal reference not permitted!
/request/{id2}:
$ref "#/components/paths/commonrequest" # components can't hold PATH objects!
/request/{id3}:
$ref "http://external.com/commonrequest.yaml";
However, even if one were to use the only permitted option, it creates a
problem if a Swagger.IO online editor user is trying to reference the main
documents "#/components/..." from the forced external YAML file. Example:
commonrequest.yaml content:
---
get:
responses:
200:
description: OK
schema:
$ref: "#/components/schemas/schema1"
...
In this case, it appears that the Swagger.io online editor will NOT first
resolve the external references, and afterwards resolve the internal
references. I have found that any schemas, parameters, responses,... found in
the main documents "#/components" true are NOT processed by the editor! They
are treated as if they are empty.
In theory, a work-around would require to change the external YAML document so
that it uses fully qualified external back-references to the main document -
but that is very cumbersome/inflexible/counter-intuitive at best, to outright
impossible at worst (because the main document URL is not defined when using
the Swagger.io online interactive editor).
It conclusion it seems to me as if the specs of the PATH object $ref are not
well thought-out, as they should come with support for matching "components"
entities, or at least support internal references (for reusing). Alternatively,
it would seem that the de-referencing order of "components" objects in external
files should be well defined - with my vote going for resolving external paths
references first, and THEN using the assembly result to resolve any internal
references.
--
You received this message because you are subscribed to the Google Groups
"Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to swagger-swaggersocket+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to swagger-swaggersocket+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
