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 [email protected].
For more options, visit https://groups.google.com/d/optout.
